FluxDeployDocs
Topics: Error Codes

Error Codes

When the FluxDeploy agent encounters a fatal error during deployment, it halts immediately with a specific error code and posts the error to the server. These codes appear in the Devices console view and deployment logs.

Startup Errors

These happen before the agent has reached the server, so they are not on the machine's page. The agent saves a support bundle to the machine and to any attached USB drive.

Code Phase Meaning Remediation
INSECURE_SERVER_URL Startup The server address in the boot image is plain http://. The agent will not send anything to it unencrypted. Rebuild the boot image so it uses the server's HTTPS address.
NO_SERVER_URL Startup The boot image has no server address Rebuild the boot image from Boot Images. If you boot a hand-made image, it needs a serverUrl in agent.config.json.
AGENT_STARTUP_FAILURE Startup The agent stopped before it could start a deployment Take the support bundle from the USB drive (or X:\Deploy\Logs) and check the message on screen. Rebuild the boot image if it is older than the server.

Authentication Errors

Code Phase Meaning Remediation
AUTH_REQUIRED Agent Password No password entered when the server requires one Enter the boot password when prompted, or embed it in the boot image configuration
AUTH_FAILED Registration Agent password was rejected by the server (HTTP 401) Verify the boot password in Settings > Deployment > Agent matches what the agent is sending

Pre-Flight Errors

Code Phase Meaning Remediation
NOT_UEFI Startup firmware_type environment variable is not UEFI Disable CSM/Legacy boot in the machine's BIOS/UEFI settings. FluxDeploy requires UEFI boot mode.
DISK_NOT_FOUND Pre-flight No eligible local disk was detected Ensure storage drivers are included in the WinPE boot image. Check that the disk is physically connected and healthy.
NIC_NOT_FOUND Pre-flight No enabled network interface was found Ensure network drivers are included in the WinPE boot image. Check physical cable connection.
DHCP_TIMEOUT Pre-flight No DHCP lease obtained after 60 seconds Verify DHCP server is running and the machine is on the correct VLAN. Check NIC driver compatibility.
GATEWAY_UNREACHABLE Pre-flight All gateway ping attempts failed Verify network connectivity. Check switch port configuration and VLAN assignment.

Server Connection Errors

Code Phase Meaning Remediation
SERVER_UNREACHABLE Check-in The machine reached the server, but the secure connection was refused. Usually the server's certificate has changed since the boot image was built, so the certificate the image trusts no longer matches. Rebuild the boot image so it carries the current certificate.
SERVER_UNREACHABLE_NETWORK Check-in The network is up (DHCP and the gateway answered) but the server address in the boot image cannot be reached Check the address in the message: it may be wrong in the image, not resolve in DNS here, or be blocked by a firewall. Rebuild the boot image if the server's address has changed.
CHECKIN_FAILED Check-in The server accepted the check-in but sent back an empty answer Check the server log at the time of the failure, then retry. If it recurs, update the server and rebuild the boot image so both are the same version.
NO_RECIPES Recipe selection The server has no active recipe for this machine to use Activate a recipe on Recipes. On a relay site, make sure the recipe is in one of the site's relay groups.
RECIPE_SELECTION_FAILED Recipe selection The server sent an empty answer when the recipe was chosen Retry. If it recurs, check the server log at that time.
RECIPE_ASSIGNMENT_FAILED Recipe selection The server accepted the chosen recipe but did not send it back Check that the recipe is still active and was not deleted while the machine was waiting, then retry.

Disk Errors

Code Phase Meaning Remediation
AMBIGUOUS_DISK Disk Selection More than one internal disk was eligible and no valid disk was chosen at the machine: an invalid number, or no answer within an hour Nothing was wiped. Boot the machine again and choose the disk at its keyboard, or detach the disk that must not be wiped so only one is eligible.
WIPE_ABORTED Confirmation A key was pressed during the 30-second unattended countdown, so nothing was wiped Intended: the countdown exists so a machine that network booted by mistake can be stopped. Boot the machine again to retry.
DISK_CHANGED Partitioning Immediately before wiping, the selected disk number no longer had the same model, size and serial (a disk was added or removed after selection), or the inventory could not be re-read. Nothing was wiped. Boot the machine again so the disk is selected afresh.
CONFIRM_TIMEOUT Confirmation No operator input received within 1 hour, or the answer was not yes Re-run the deployment. The confirmation prompt requires typing yes to proceed. An unattended boot image still prompts when the recipe does not allow unattended deployment (see Recipes).
PARTITION_FAILED Partitioning diskpart returned a non-zero exit code, or ESP/Windows partitions were not created Check disk health. Ensure the disk is not write-protected. Review the diskpart script output in the console.

Imaging Errors

Code Phase Meaning Remediation
IMAGE_DOWNLOAD_FAILED Imaging Network connection lost during WIM download and still lost after 3 resumes, or the relay is re-downloading an image its cache removed Check network stability. Verify the server/relay is reachable. If the message says the relay is downloading the image again, wait a few minutes and retry. The error includes network troubleshooting hints.
MULTICAST_INTEGRITY_FAILED Imaging The image assembled from a multicast session did not match its SHA-256 Not fatal on its own - the copy is deleted and the agent downloads the image ONCE over unicast, which is verified the same way. Recurring warnings mean this network corrupts (or someone is interfering with) the multicast stream: turn multicast off for it.
INTEGRITY_FAILED Imaging SHA-256 hash of the downloaded WIM does not match the expected value Re-download the image. If persistent, re-upload the WIM to the server and verify the source file integrity.
IMAGE_APPLY_FAILED Imaging DISM /Apply-Image returned a non-zero exit code Check available disk space on the Windows partition. Review DISM output in the console for specific errors. Verify the WIM file is not corrupted.

Post-Imaging Errors

Code Phase Meaning Remediation
BCDBOOT_FAILED Boot Config bcdboot.exe returned a non-zero exit code Verify the EFI System Partition (S:) was created correctly. Check that W:\Windows exists and contains a valid installation.
DRIVER_DOWNLOAD_DENIED Drivers The server refused this machine's deployment token (HTTP 401/403) when it downloaded a driver package The deployment stops rather than finish without storage, chipset or network drivers. Check the server log for the refusal. Usually the server is older than the agent (update the server and rebuild the boot image), or another machine checked in with the same serial number.
DRIVER_INTEGRITY_FAILED Drivers A downloaded driver package did not match the SHA-256 the server recorded for it. It was deleted without being extracted. Re-upload the driver package. If it recurs, check the network path between the machine and the server.
DRIVER_INJECT_PARTIAL Drivers One or more DISM /Add-Driver calls failed Non-fatal - deployment continues. Review which drivers failed in the console. The affected hardware may need manual driver installation post-deployment.
ANSWER_FILE_FAILED Answer File The server did not provide the recipe's answer file (any answer other than 200, or no answer in time) The deployment stops, because Windows would otherwise set up with no computer name, local Administrator password or domain join. A 401 usually means another machine checked in with this machine's serial number; otherwise check the server log.
FIRSTBOOT_REGISTER_FAILED FirstBoot Setup The target's SOFTWARE registry hive could not be loaded, or the RunOnce entry that launches the FirstBoot steps could not be written The FirstBoot steps would never have run. Check that the image applied cleanly (DISM output in the console) and retry.
COMPLETE_REFUSED Completion The server refused the success report (HTTP 401/403), so it never recorded the deployment as complete Check the Machines page: another machine may have checked in under this machine's serial number and taken over its record.

Task Sequence Errors

Code Phase Meaning Remediation
TASK_STEP_FAILED Task Steps A step exited with a non-zero code and ContinueOnError is false Review the step's output in the console. Fix the script or enable ContinueOnError if the failure is acceptable.
TASK_STEP_TIMEOUT Task Steps A step exceeded its configured timeout Increase the step's timeout value, or optimize the script. Default is 300 seconds, maximum is 7200 seconds.
TASK_CONDITION_ERROR Task Steps Malformed condition JSON on a step The step is skipped with a warning (non-fatal). Fix the condition JSON in the recipe's task sequence editor.
FIRSTBOOT_UNSUPPORTED_VARIABLE FirstBoot Setup A FirstBoot PowerShell step uses %WINDOWS_DRIVE%. FirstBoot steps run after Windows has started, where that drive letter no longer exists, and PowerShell does not expand %...% variables. Write $env:SystemDrive in the script instead, or move the step to a WinPE phase. The message names the step.
FIRSTBOOT_WINPE_PATH FirstBoot Setup A FirstBoot step still points at the drive letter the Windows volume has only during WinPE (usually W:). After the restart that letter is gone. Replace the drive letter in the step with %SystemDrive%. The message names the step.

Autopilot Errors

Code Phase Meaning Remediation
AUTOPILOT_PROFILE_INVALID Autopilot Autopilot for existing devices: the Autopilot profile the server sent could not be used. Nothing was written to the machine. Fix the profile on Settings > Cloud Integrations > Autopilot (the message names the reason) and deploy again. See Autopilot.
AUTOPILOT_PROFILE_WRITE_FAILED Autopilot Autopilot for existing devices: the profile was valid but could not be written to the Windows volume Treat it as a disk or permissions problem on the applied image. Check the imaging output in the console and deploy again.
AUTOPILOT_REGISTRATION_FAILED First boot The server refused to register this device in Autopilot. The machine was left as it is and was not prepared for the Autopilot setup screens. Read the reason on the machine's page and in the diagnostic bundle collected for it. A device preparation recipe deployed with an old boot image also ends here: rebuild the boot image after upgrading. See Autopilot.
AUTOPILOT_SYSPREP_FAILED First boot The device is registered in Autopilot, but Windows could not be prepared (sysprep) for the Autopilot setup screens The machine is still signed in as the temporary first-boot account and is safe to log into. Check C:\Windows\System32\Sysprep\Panther\setuperr.log or the diagnostic bundle, fix the cause and deploy again. See Machine Detail.
AUTOPILOT_BUNDLE_COLLECTOR_MISSING First boot Non-fatal. A failure above wanted to collect a diagnostic bundle, but the collector was not on the machine The first-boot log C:\Windows\Temp\fluxsysprep.log is still on the machine. Rebuild the boot image so the collector is included.
AUTOPILOT_BUNDLE_FAILED First boot Non-fatal. The diagnostic collector ran but did not produce a bundle Use the first-boot log C:\Windows\Temp\fluxsysprep.log on the machine instead.

Unexpected Errors

Code Phase Meaning Remediation
UNEXPECTED_PHASE_FAILURE Any A deployment step failed in a way the agent does not have a specific code for. The message names the step. Credential files were removed from the disk and the machine was not deployed. Take the support bundle and report the message. Check the recipe's task steps first if the failing step is one of them.
NO_TASK Any The agent reached a deployment step without the details from check-in. This should not happen. Boot the machine again. If it recurs, rebuild the boot image and report it with the support bundle.