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 internal assignments and imported TPA-backed ABAC factors validate for the resolved peer (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 Policy Manager 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
tpa_requires_verified_preflight The profile contains imported TPA-backed ABAC IDs, but deployment is using the legacy non-verified path Re-run the deployment with verified preflight so the resolved peer snapshot can validate the imported TPA factors

Verified Snapshot ABAC Failures (Step 7)

When verified preflight resolves a peer snapshot, ntkDeploy validates each ABAC ID in the profile against that resolved peer only. These are the exact failure codes currently emitted by the snapshot-backed validator.

Profiles still persist ABAC as string IDs. Internal attribute IDs and imported TPA tpaId values share the same matrix, so same-org and collision cases fail closed instead of being guessed or auto-corrected.

Failure code Meaning Remediation
abac_internal_missing An internal attribute ID is not present in the resolved peer snapshot Add the missing internal assignment or remove the ID from the profile
abac_internal_expired The resolved peer snapshot contains only expired internal assignments for that ID Renew the internal assignment or remove the ID from the profile
abac_tpa_missing_import No imported TPA entry for that ABAC ID was present in the resolved peer snapshot Import the grant for the resolved recipient, or remove the ID from the profile
abac_tpa_unresolved_grant A snapshot entry exists, but it does not resolve to a usable grant Re-import or replace the grant so the import resolves cleanly
abac_tpa_trust_missing No matching trust exists for the issuing organization Create or restore the TPA trust for the issuer org
abac_tpa_trust_suspended The matching trust exists but is suspended Reactivate the trust or remove the imported TPA factor
abac_tpa_scope_not_allowed The trust does not allow the imported grant's scope type Update the trust or use a grant whose scope is allowed
abac_tpa_permission_not_allowed The trust does not allow the imported grant's permissions Narrow the grant or widen the trust deliberately
abac_tpa_issuer_key_not_pinned The trust does not pin the issuer signing key used by the grant Add the issuer key to the trust or import a grant signed by a pinned key
abac_tpa_expired The imported grant is past its endDate Renew or replace the imported grant
abac_tpa_not_yet_valid The imported grant's notBefore window has not opened yet Wait for the validity window or import a grant with the correct timing
abac_tpa_recipient_mismatch The imported grant does not apply to the resolved person, peer fingerprint set, or org Import a grant scoped to the resolved recipient, or remove the ID from the profile
abac_tpa_same_org_invalid A same-org TPA grant appeared where a cross-org imported grant is required Replace the same-org grant with an internal attribute or a valid cross-org TPA import
abac_factor_id_collision One canonical ABAC ID resolves to both an internal factor and an imported TPA factor Resolve the ID collision before deployment; ntkDeploy will not choose one source automatically

All verified snapshot ABAC failures are fail-closed. Validation output references canonical ABAC IDs only; raw TPA key material is never included.

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, tpa_requires_verified_preflight.
  • 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.

TPA Preflight Findings

When the Policy Manager reports tradingPartnerAttributes: true, the preflight pipeline evaluates TPA grants and imports alongside ABAC assignments. TPA findings are returned in the same PolicyManagerPreflightFinding envelope as ABAC findings and are displayed together in the preflight review step.

A single blocking TPA finding prevents deployment for all affected devices.

These server-side TPA finding codes are distinct from the client-side verified snapshot ABAC failure codes above (abac_tpa_*).

Finding code Severity Blocking Remediation
TPA_MISSING_TRUST error yes Create a trust relationship for the issuer organisation under TPA Trusts before importing grants from them
TPA_INVALID_ISSUER error yes The grant issuer key is not in the trust's trusted keys; update the trust or ask the issuer to reissue the grant with a key your trust accepts
TPA_DUPLICATE_ID error yes Two active grants share the same TPA ID; revoke one
TPA_ID_CONFLICTS_INTERNAL error yes The TPA ID conflicts with an internal attribute definition; rename the internal attribute or revoke the TPA grant
TPA_MALFORMED_KEY error yes The TPA key is the wrong length; ask the issuer to reissue the grant
TPA_MALFORMED_ID error yes The TPA ID is the wrong length; recreate the definition with a valid 32-character hex ID
TPA_EXPIRED warning no The grant has passed its endDate; renew or revoke it (deployment is not blocked, but the expired grant will not contribute to access decisions)
TPA_NOT_YET_VALID error yes The grant's notBefore is in the future; wait until the validity window opens or ask the issuer to adjust notBefore
TPA_REVOKED error yes The grant or import record is revoked; remove or replace it
TPA_RECIPIENT_MISMATCH error yes The current peer is not in the grant's recipient binding; check recipientMode on the grant
TPA_SCOPE_NOT_ALLOWED error yes The grant's scope type is not in the trust's allowedScopeTypes; update the trust to include the required scope
TPA_PERMISSIONS_EXCEED_TRUST error yes The grant contains permissions that exceed what the trust allows; update the trust or ask the issuer to reissue with narrower permissions
TPA_EMPTY_SCOPE_TYPES error yes The trust's allowedScopeTypes list is empty; edit the trust record and add at least one scope type
TPA_CANONICAL_HASH_MISSING error yes The grant record has no canonical hash; the issuer must recreate the grant using a version of ntkDeploy that computes the signature correctly

TPA_EXPIRED is the only non-blocking TPA finding. All remaining 13 codes are blocking errors that must be resolved before deployment can proceed.

Unknown TPA finding codes (returned by future server versions) are displayed with the raw code and no guidance string rather than being silently suppressed.

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.

For TPA-enabled environments, the same preflight review can contain both ABAC and TPA findings. Deployment remains fail-closed whenever any blocking finding is present.

Next Steps