FluxDeployDocs
Topics: Troubleshooting

Troubleshooting

Common issues encountered during FluxDeploy deployment and their solutions.

PXE Boot Issues

Machine does not PXE boot

  • Verify UEFI boot mode is enabled in BIOS (disable CSM/Legacy)
  • Check that PXE/Network Boot is enabled in BIOS boot options
  • Confirm the DHCP server is providing the correct boot options (option 66 = server IP, option 67 = bootmgfw.efi)
  • If using ProxyDHCP, ensure port 67 and 4011 are not blocked by a firewall
  • Verify the FluxDeploy PXE service is running: check Settings > PXE & Network Boot
  • Check PXE logs at logs/pxe/ (enable PXE logging if needed)

PXE boot starts but hangs loading boot.wim

  • This typically indicates a TFTP transfer issue. Check:
    • TFTP block size - try switching to Compatible mode in PXE settings if using High Performance mode
    • Network switches with strict MTU settings may drop large TFTP packets
    • Firewall rules on UDP port 69
  • Verify boot.wim exists in {BootFilesPath}/tftp/sources/boot.wim

WinPE boots but has no network

  • The boot image is missing network drivers for the target hardware
  • Download appropriate WinPE drivers from the OEM catalog on the WinPE Drivers page
  • Rebuild the boot image with the new drivers selected

Deployment Failures

INTEGRITY_FAILED - SHA-256 mismatch

  • The WIM file was corrupted during transfer
  • Check network stability between the agent and server/relay
  • Re-upload the WIM to regenerate the hash
  • If using a relay, force sync to re-download the image

IMAGE_APPLY_FAILED - DISM apply error

  • Check available disk space on the Windows partition
  • Review DISM output in the live console for specific error messages
  • Common cause: corrupted WIM file - re-create or re-upload the image
  • Ensure the disk is healthy (no bad sectors or hardware failure)

DRIVER_INJECT_PARTIAL - Some drivers failed

  • This is non-fatal - deployment continues with the successful drivers
  • Review which specific drivers failed in the console output
  • Common cause: driver INF incompatibility with the target Windows version
  • Verify the driver package's Supported Windows Versions setting matches the deployed image

Deployment stuck at "Imaging" status

  • Check the live console on the Devices page for the actual agent state
  • Network interruption during WIM streaming can cause a stall
  • If the connection drops, the agent resumes the download from where it stopped, up to 3 times (waiting 2, 4 and 8 seconds); it reports IMAGE_DOWNLOAD_FAILED only when the connection keeps dropping
  • Verify server/relay connectivity and bandwidth

Relay Issues

Relay shows "Unreachable" on Core

  • Verify network connectivity between Core and Relay (HTTPS port 8400)
  • Check the relay service is running (sc query FluxDeployRelay on Windows, systemctl status fluxdeploy-relay on Linux)
  • Verify the relay.json has the correct Core URL and API key
  • Check the relay's sync log at logs/sync/relay-sync-{date}.log
  • If Core's TLS certificate changed, the relay may be rejecting connections - check for certificate errors in the log. The relay auto-updates the thumbprint on next successful heartbeat.

Relay sync shows "Missing" items

  • Click Force Sync on the Sites page to trigger an immediate sync
  • Check available disk space on the relay's data drive
  • Review the relay sync log for download errors
  • Verify the relay site's relay group (Relay sites > Relay groups) has the expected active recipes and additional drivers

Boot Image Issues

Boot image build fails

  • Verify Windows ADK and WinPE Add-on are installed on the Core server
  • Check the build log on the Boot Images page for specific errors
  • Ensure the Server Address is configured in Settings > General > Organization
  • Verify sufficient disk space for the build staging directory

Agent cannot connect to server after boot

  • The TLS certificate thumbprint embedded in the boot image does not match the server's current certificate
  • Rebuild the boot image after any certificate change
  • Check that the Server Address in Settings matches what the agent is trying to reach
  • Verify firewall rules allow HTTPS traffic on port 8400

General

Login fails with "Too many attempts"

The login rate limiter has locked the account. Wait 15 minutes (default lockout duration) or restart the service to clear the rate limiter state. Adjust limits in Settings > Security.

Upload fails for large files

  • Check the configured upload limit in Settings > Security > Upload Limits
  • Default driver upload limit is 5 GB (configurable), WIM limit is 10 GB, ISO limit is 20 GB
  • "Not enough free disk space" means the data drive cannot hold the file; the message gives the size needed and the space free. Free some space or move the data folder to a larger drive
  • A refusal always says why (wrong file type, damaged file, missing name). A driver upload must be a .cab or .zip; an .exe is refused
  • For very slow connections, uploads may timeout - Kestrel's data rate limits are disabled by default, but check network proxy/load balancer timeouts

Support bundle

Settings > Diagnostics & Info > Download Support Bundle builds a zip that lets support diagnose a problem without remote access. Admin and Read Only users can generate and download it; Operators cannot. Starting and each download are recorded in the audit log.

Generating takes from a few seconds to about two minutes (the cloud checks wait on the services they test), so the button opens a Generating the support bundle screen instead of a download that seems to hang. It lists each part with an icon (waiting, running, done, could not be collected, not configured) and a running timer. Cancel stops it and deletes everything it built. When it finishes, the download starts by itself and a Download button stays available; a short line says how many parts were collected and how many cloud checks failed. If a part failed, the screen says so in plain words and the bundle is still offered. If you close the page and open it again while it runs (or after it finishes), the screen reattaches to the same job. There is one shared job: a second click while one is running shows the running job. A finished bundle is deleted after 15 minutes or once it has been downloaded, and leftovers from a crashed server are removed at startup.

File What it contains
manifest.txt Every file with its size and whether it collected, the date range the logs cover, and the redaction rules applied. Start here.
system-info.txt Product version and mode, Windows version and build, uptime and last boot, .NET runtime, CPU, RAM, this process's memory/threads/handles, time zone, and the database provider (plus SQL Server edition and version).
disk-and-paths.txt Free space on each fixed drive and the size of the FluxDeploy folders (images, drivers, ISOs, PXE, logs; the size count stops after a bounded time and says "at least"), with the folder permissions.
database.txt Applied and pending migrations, a row count per table (counts only, never contents), database size and a connection latency check.
settings.json The name of every setting. Values are shown only for a short list of safe settings (switches, numbers, timestamps, states); everything else shows [REDACTED].
jobs.txt Recent driver downloads, image customizations, boot image builds and relay boot image builds: status, times and the status message.
sites.txt Relay sites (name, status, version, last heartbeat, database provider, PXE state, health), or on a relay its connection to Core.
certs-and-license.txt Certificate subjects, thumbprints and expiry dates, the CA chain (public certificates only), ACME status, and the license state (status, expiry, limits, trial days left).
eventlog.txt Windows Application and System errors and warnings from the last 7 days for FluxDeploy, SQL Server, .NET, Service Control Manager and Windows Update, plus unexpected shutdown and reboot events. On a Linux relay, the tail of the relay service journal.
services-and-ports.txt State of the FluxDeploy and SQL Server services, which process listens on each port the product uses, and whether a firewall rule allows each.
cloud-checks.txt The result of read-only checks against every cloud or external service that is configured: Microsoft Graph (the Autopilot tenant: cloud, sign-in host and the permissions the token carries), Azure for Connected Cache, the ACME CA and its port 80 listener, SMTP (connect, EHLO, STARTTLS; no mail is sent), the SAML identity provider's signing certificate, each notification channel's host (nothing is posted), the vendor download hosts you have used (HP, Dell, Lenovo, Microsoft), relay heartbeat age, this server's DNS name, outbound HTTPS, the clock against a web server's Date header, and the proxy in effect. Each shows what was tested, the host name, the result, elapsed time and a short reason (DNS failed, TCP refused, TLS error, HTTP status, auth refused, timed out). Unconfigured items say "not configured".
tftp-files.txt, last-agent-config.json PXE boot file fingerprints and the last agent configuration written into a boot image (every token and thumbprint value shows [redacted]).
logs/ The newest application and PXE logs from the last 14 days. Each file is capped; when one is longer, the end is kept and the manifest says so. Every line passes the credential scrub described below.

What is never included: passwords, API keys and their hashes, bearer tokens, license keys, registration keys, tenant and client secrets, SAML data, certificate private keys or PFX files, connection strings, webhook URLs, and the contents of images, ISOs and drivers. Every text file in the bundle, the logs included, goes through a scrub that masks Authorization and X-Api-Key headers, Bearer and JWT values, password=, pwd=, secret=, token=, apikey= and similar in key=value, JSON and URL-query forms, passwords inside URLs, connection-string credentials, PEM blocks and SAML payloads. Ordinary log lines pass through unchanged.

Cloud checks are read-only and run only when you ask. They use GET and HEAD requests, DNS lookups and TLS or SMTP handshakes; the one request that is not a read is the sign-in the product already makes to obtain a Graph token. They never register a device, issue or renew a certificate, send an email, post a message, create or change anything in Azure, or run on a timer. Each check has a 10 second limit and the whole set 90 seconds; a check that hangs shows "timed out". Vendor results are reused for a few minutes so repeated bundles do not hammer a vendor. The same checks run from Settings > Diagnostics & Info > Connectivity Tests > Cloud & Integrations.

If one part cannot be collected, that file contains could not collect: and a short reason, and the rest of the bundle still downloads. Check manifest.txt for which parts were affected.