Skip to content

Common Issues

This page covers the most frequently encountered problems when running ntkDeploy, with symptom, likely cause, and the steps to resolve each one. For deployment-specific failures see Deployment Failures; for UNC/SMB problems see Connectivity Issues.

Prerequisites

  • ntkDeploy installed on a supported Windows machine — see Installation.
  • Access to Windows Task Manager, Event Viewer, and PowerShell for diagnostic steps.

App Fails to Start

Symptom

The ntkDeploy window never appears after launch. You may see a brief splash or nothing at all.

Likely Causes

Cause Indicator
Windows version too old Crash log in %LOCALAPPDATA%\ntkDeploy references a missing Windows API
Missing Visual C++ Redistributable A dialog mentions VCRUNTIME140.dll or similar
MSIX trust not established Windows SmartScreen blocks the package; installer exits silently

Resolution

  1. Check Windows version. ntkDeploy targets Windows 10 (build 19041+) and Windows 11. Run winver to confirm.
  2. Install the Visual C++ 2015–2022 Redistributable (x64) from the Microsoft Download Center and retry.
  3. Re-run the install script. The bundled scripts/install_msix_trust_and_app.ps1 installs the CA certificate that allows the MSIX to be trusted. Run it in an elevated PowerShell session: 
    Set-ExecutionPolicy Bypass -Scope Process
.\scripts\install_msix_trust_and_app.ps1
  4. If the app still won't start, check the Windows Event Viewer under Windows Logs → Application for Flutter or Dart runtime errors.

Database Locked or Corrupted on Launch

Symptom

ntkDeploy opens but shows an error banner such as "DatabaseException: database is locked" or "database disk image is malformed" on the Dashboard. The app may be otherwise unresponsive.

Likely Causes

Cause Indicator
Previous instance did not exit cleanly Two ntkDeploy processes are running
Power loss / OS crash during a write Error persists after a clean restart
Disk full when the journal was being flushed Low disk space on startup drive

Resolution

  1. Check for duplicate processes. Open Task Manager, look for multiple ntk_deploy.exe entries, and terminate all but one.
  2. Restart the application — a clean startup usually releases stale locks.
  3. If the database is corrupted, the SQLite file can be found at: 
    %APPDATA%\com.jibberishdev.ntk_deploy\
    Make a backup of app.db, then delete it. ntkDeploy will recreate the schema on next launch. Profiles and groups stored in the old database will be lost — recover them from exported JSON if available.
  4. Check available disk space with Get-PSDrive C in PowerShell. ntkDeploy's SQLite journal requires free space to commit transactions.

Note: Schema migrations run automatically on startup (schema version 2 adds DeviceGroupPaths). If a migration is interrupted, the database may be left in an inconsistent state — delete and recreate in that case.

Profiles Not Appearing After Import

Symptom

A JSON file was imported but no new profile appears in the Profiles list, or the import dialog closed without a confirmation.

Likely Causes

Cause Indicator
Schema version mismatch Import dialog reported a conflict or validation error
Environment filter active The imported profile belongs to a different environment
Duplicate ID conflict A profile with the same ID already exists and was skipped

Resolution

  1. Check the active environment. Profiles are scoped per environment. Ensure the environment selected in the left sidebar matches the one embedded in the imported file. See Environments.
  2. Re-open the Import dialog (Profiles → Import) and inspect any validation or conflict messages. If a conflict is reported, choose Overwrite to replace the existing profile, or Auto-Rename to import it alongside the current version with a new name.
  3. Validate the source JSON. Open the file in a text editor and verify the top-level structure is an object ({}), that schemaVersion is populated, and that no fields contain non-UTF-8 characters.
  4. If the import dialog closed silently, check the Audit Log for a profile_created or profile_updated event — the import may have succeeded even though no toast was shown.

Policy Status Stuck on "Connecting"

Symptom

The Policy Manager section or the policy status indicator in the sidebar shows "Connecting..." or "Unavailable" indefinitely and never transitions to "Ready".

Likely Causes

Cause Indicator
Policy server not configured Settings → Policy Server → Base URL is blank
Wrong Base URL URL uses http:// instead of https://, or port is wrong
TLS certificate mismatch Test Connection returns a CERTIFICATE_VERIFY_FAILED error
Policy server unreachable from this machine Test Connection times out

Resolution

  1. Open Settings → Policy Server and confirm all required fields are populated:
  2. Base URL — must be https://host:port, e.g. https://policy.example.com:8443
  3. CA certificate path — must point to the CA .pem or .crt file that signed the server certificate
  4. Client certificate path and Client key path — required for mutual TLS
  5. Click Test connection. Review the snack bar for the exact error text.
  6. If the test succeeds but the status is still stuck, restart ntkDeploy. The connectivity gate initialises at boot; a clean restart resets the gate evaluation cycle.
  7. If the test fails with a TLS error, verify the certificate files match the server and are not expired (openssl verify -CAfile ca.pem client.pem in a terminal).
  8. Confirm the machine running ntkDeploy can reach the server: Test-NetConnection -ComputerName policy.example.com -Port 8443 in PowerShell.

Further reading: Settings Reference → Policy Server • Deployment Preflight — connectivity gate codes

Device Groups Showing Stale Connectivity Results

Symptom

The connectivity badge on a device group path shows "Last checked: X hours ago" or displays "unreachable" even though the share is known to be online.

Likely Causes

Cause Indicator
Preflight was not re-run after network change Timestamp on the badge is old
VPN was not active during last check Badge status unreachable with no access error
UNC path changed on the server Status unreachable after infrastructure change

Resolution

  1. Open the Device Group detail page and tap Run Preflight (or the refresh icon next to the path) to force a fresh connectivity check.
  2. If re-running returns unreachable, verify the share exists and the UNC path is correctly formatted — see Connectivity Issues for full diagnosis steps.
  3. If your environment uses a VPN, ensure it is connected before running preflight checks.
  4. To update a stale path, edit the Device Group and correct the UNC path, then re-run preflight.

Profile Validation Errors

Symptom

The Deployment Wizard stops at the schema validation step and displays one or more validation_failed errors, or the profile editor shows inline red-bordered fields that prevent saving.

Likely Causes

Cause Indicator
Required field left blank Field-level error message: "This field is required"
Value out of allowed range Numeric or enum field shows a constraint violation message
Schema version mismatch Import succeeded but the payload was built against an older schema
Non-UTF-8 characters in a text field Save operation fails silently or with a database encoding error

Resolution

  1. In the profile editor — hover over or click any red-bordered field to read the specific validation message. Fix each flagged field and save. The editor will not allow navigation to the next step while required fields are invalid.
  2. In the Deployment Wizard — the wizard lists each failing gate code. Select the profile in the error list and choose Edit profile to open the editor directly.
  3. After import — if a recently imported profile fails validation, open it in the editor to inspect fields. The imported schemaVersion must match the registered v1.0 schema. If it doesn't, update the profile fields to conform and save a new version.
  4. Encoding issues — paste the text content into a plain-text editor (Notepad) and re-enter any suspect characters to strip non-UTF-8 bytes.
  5. Check the Audit Log for profile_validation_failed events — the details payload lists each failing field and the violated rule.

See Profile Schemas Reference and Deployment Preflight Reference.

Missing or Stale Data After Environment Switch

Symptom

After switching environments (Development → Staging → Production or vice versa) the profile list, device group list, or dashboard statistics appear empty, show outdated counts, or display items that belong to the previous environment.

Likely Causes

Cause Indicator
Environment filter not yet applied Sidebar shows the new environment but the view hasn't refreshed
No data promoted to the target environment Correct environment is active but the list is genuinely empty
Search query still active across switch Global search bar has text that filters out all items
Dashboard statistics cached from previous session Counts on the Dashboard do not match the list view

Resolution

  1. Confirm the active environment. The environment name is shown in the left sidebar header. If the display looks wrong, click the environment selector again to force a reload.
  2. Check for an active search query. Clear any text in the global search bar or inline list filter — a leftover query can make the list appear empty.
  3. Move data to the target environment if it is genuinely empty. Profiles are environment-scoped. To copy a profile to another environment, clone it in the Profiles screen (the Clone action copies all settings) and change its Environment label. See Environments.
  4. Reload dashboard statistics. Navigate away from the Dashboard and back — this triggers a fresh database query. If counts still look wrong after a full restart, open the Audit Log to verify the actual record count for the current environment.
  5. If data appears from the wrong environment after switching, restart ntkDeploy. The environment state is held in memory; a clean launch re-reads it from the database.

Global Search Returning No Results

Symptom

Typing a profile name or group name in the global search bar returns an empty list or no results despite the items existing.

Likely Causes

Cause Indicator
Searching in the wrong environment context Items exist in a different environment
Search index not yet built App was just launched; loading spinner still active
Minimum character threshold not met Only 1–2 characters typed

Resolution

  1. Check the environment indicator in the left sidebar. Global search scopes results to the active environment — switch to the correct environment and search again.
  2. Wait for the Dashboard to finish loading statistics (the first load populates the search index from the local database).
  3. Type at least 3 characters to exceed the debounce threshold.
  4. If results are still missing, navigate directly to Profiles or Device Groups and use the inline list filter to confirm the item exists in the current environment.

Next Steps