Skip to content

Deployment Preflight Reference

Before any configuration is written to a device, ntkDeploy runs a series of preflight checks. These checks are fail-closed: if any hard failure is encountered the deployment is blocked and no artifact is written.

Prerequisites

When Preflight Runs

Preflight checks run at two distinct moments:

Trigger Checks performed
Build JSON payload (save or dry-run) Steps 1–5 below (schema pipeline only)
Deploy with policy enforcement Steps 1–7 below (schema pipeline + policy pipeline)

Check Pipeline

Steps 1–5: Schema Validation Pipeline

These checks run for every profile version before saving or deploying.

# Check Pass criteria Fail code Remediation
1 Validation status Profile version status is valid invalid_state Open the profile editor and re-validate with Ctrl+Enter
2 JSON decode settingsJson is valid JSON with no syntax errors invalid_json Edit the Raw JSON view to fix malformed JSON
3 Root structure Decoded value is a Map<String, Object?> — not an array or primitive invalid_format Ensure the JSON root is an object {}
4 Schema validation All fields pass the rules defined in schema v1.0 (see Profile Schemas Reference) schema_validation Review the listed field errors in the editor
5 Re-encode Settings re-encode to minified JSON without error invalid_json Resolve any encoding issues flagged in step 4

Steps 6–7: Policy Enforcement Pipeline

When the deployment uses policy enforcement, two additional checks apply. The connectivity gate (step 6) is evaluated first — before the ABAC branch is even reached. If the gate is closed or unavailable, the build fails immediately without inspecting the profile's ABAC configuration. The per-device policy preflight (step 7) runs only when ABAC attributes are detected in the profile.

# Check Pass criteria Fail code Remediation
6 Policy connectivity gate The Policy Connectivity Gate is open (checked before ABAC detection) policy_connectivity_gate_closed or policy_connectivity_gate_unavailable Open Settings → Policy Server and use Test Connection to restore the gate; restart the app if the gate service is unavailable
7 Policy preflight Profile has ABAC attributes configured; policy server is reachable; device identity resolves; all required ABAC assignments are present and non-expired (various — see below) See policy preflight failure codes

Orchestration-Level Failures (Step 6 — connectivity gate)

These codes are returned before per-device preflight runs.

Failure code Meaning Remediation
policy_connectivity_gate_closed Gate is closed due to a previous connectivity failure Check policy server reachability; the gate is re-evaluated by the connectivity monitoring service — use Settings → Test connection to verify endpoint reachability, but gate state is controlled by the monitoring service, not the test action directly
policy_connectivity_gate_unavailable Gate service not initialised Restart ntkDeploy

Per-Device Preflight Failures (Step 7)

These codes are emitted by the per-device preflight service. When the deployment pipeline processes these results it applies an additional classification step before propagating failures to the caller — see Error Code Classification below.

Failure code Meaning Remediation
server_unreachable Policy server did not respond to the ping Check Base URL, CA cert, and client cert in Settings
device_owner_unassigned No person is assigned as owner of this device key Assign a person in Device Groups before deployment
fetch_failed Could not retrieve assignments or attribute definitions from the policy server Check policy server connectivity
attribute_not_found A required ABAC attribute definition was not found on the server Verify attribute IDs in the profile match definitions on the policy server
assignments_missing No valid assignment exists for a required ABAC attribute Add the missing assignments in the Policies section
assignments_expired An assignment for a required attribute has passed its expiry date Renew or remove the expired assignment
missing_attribute_key An assignment is present but its attributeKey field is empty Regenerate device credentials or contact your policy administrator

Error Code Classification

When a preflight failure occurs, the deployment pipeline classifies the raw failure code before returning it to the caller:

  • Actionable codes — passed through unchanged so the UI can present targeted remediation: assignments_missing, assignments_expired, device_owner_unassigned, validation_failed, precondition_required, precondition_failed.
  • Non-actionable codes — wrapped into a single preflight_failed failure with the original result attached as details. Codes wrapped this way include server_unreachable, fetch_failed, attribute_not_found, and missing_attribute_key.

If you observe preflight_failed in build output or audit logs, inspect the nested details field to recover the underlying raw code and message.

UNC Path Connectivity Checks

UNC path validation is a separate check performed on each destination path in a device group. It runs before the deployment wizard transmits any files.

Format Validation

The path is checked against the following rules before any network I/O:

Rule Error code Error message
Path must not be empty or have leading/trailing spaces unc_invalid_format UNC path must not be empty or contain leading/trailing spaces
Path must not contain .. segments unc_invalid_format UNC path must not contain parent directory segments
Path must use \ as separator (not /) unc_invalid_format UNC path must use \ as a separator
Path must match \\server\share[\...] unc_invalid_format UNC path must match \\server\share\path

Connectivity Check

After format validation passes, ntkDeploy attempts to verify the existence of the directory at the UNC path:

Outcome Status code Error code Remediation
Directory exists and is accessible success — No action needed
Directory does not exist failed unc_not_found Verify the share is mounted and the path is correct
Access denied or I/O error failed unc_access_error Confirm the running account has read/write permission to the share

Reading Preflight Results

Result Meaning
Pass (no errors) All checks succeeded; deployment may proceed
Hard failure One or more checks blocked deployment; no files are written
Confirmation required One or more devices have missing policy plans; admin must confirm before proceeding

The connectivity monitoring service emits two action types to the audit log as telemetry: policy_connectivity_gate (failure and error outcomes only — ready and unavailable outcomes are not persisted) and policy_capabilities_check (failure and error outcomes only). Per-device preflight failure details are returned to the caller but not recorded in the audit log.

Next Steps