Troubleshooting

Start with the session log — the client records everything.

Fast triage

Session logs (the black box)

The boot client tees its entire console session — including diskpart and network tool output, plus a phase-by-phase summary of each DISM operation (DISM's own raw console text is replaced by ImageForge's progress bar, but real DISM error text is preserved and shown on failure) — to \imageforge-logs\imageforge-<timestamp>.log on the boot USB, and uploads snapshots to the Forge whenever connected (data\clientlogs\ on the server). When something fails in the field, the whole story travels home on the stick. A companion imageforge-<timestamp>-boot-report.json records the media identity, firmware/Secure Boot state, interface/IP timeline, problem-device hardware IDs, and exact driver attempts; authenticated reports are stored under data\bootreports\.

DISM failure logs

When DISM fails, the message it prints is often only a bare Windows error code (Error: 1 — Incorrect function.). The explanation lives in DISM's own log, which inside WinPE sits on the X: RAM disk and is destroyed by the next reboot.

So on any failed capture, deploy, or driver injection, the client automatically saves the tail of that log to \imageforge-logs\imageforge-<timestamp>-dism-<stage>.log on the boot USB and uploads it to the Forge as data\clientlogs\<serial>-<timestamp>-dism-<stage>.log. Stage is capture, capture-direct, apply, or driver-inject. The error lines nearest the failure — the ones carrying the real HRESULT — are also copied into the session log itself, so they survive even when the USB is unwritable and the Forge is unreachable.

Read the HRESULT first: it names the actual failure, where DISM's console exit code does not. Nothing here is required of the technician — collection is automatic and never blocks or changes what you can do next.

Client can't find the Forge

1. Watch the connect screen — it diagnoses itself in order: adapter/link/IP → exact local-depot driver match → offline DriverStore match → hardware IDs and the remaining failure.
2. "no network hardware detected at all": NIC disabled in firmware, or the dongle/dock wasn't connected before boot.
3. "network hardware found, but no driver works": the screen prints the exact hardware IDs. Add that adapter's driver to the architecture-specific boot-driver depot and rebuild — see Driver packs, which can take a vendor pack and the printed ID directly — or connect the site's certified USB Ethernet adapter. Wireless adapters don't count — WinPE has no ordinary Wi-Fi path.
4. Plugged the dongle or dock in after boot? Choose [r] search for drivers again, not [d] retry DHCP. The boot-time driver search ran once, before that hardware existed; [r] rescans and repeats it without a reboot.
5. "no link": the driver exists, but check cable, dock power, switch port, and port state. 169.254.x.x/no IPv4 means link works but DHCP/VLAN did not. Choose retry DHCP or the client's guided static IPv4 configuration.
6. Network up but no discovery: UDP 8968 may be blocked or you're across a VLAN. Enter the Forge address manually, or request site-specific media with the Forge address preloaded.
7. Reaching the wrong/changed server: site-pinned media rejects a different TLS fingerprint. On normal USB, ISO, and PXE media, the technician access code automatically authenticates the certificate before the code is sent. No fingerprint entry is required. A writable boot USB saves the authenticated fingerprint in \ImageForge\known-forges.txt for later boots; read-only ISO and PXE media safely repeat the automatic access-code proof. If the client says the Forge is too old, update the Forge server before updating or using the boot media. If it says no code is available, create one in access and retry.

Machine boots into vendor recovery instead of the USB

Dell SupportAssist / HP Sure Recover appearing means the firmware never booted the stick. Use the one-time boot menu (Dell F12, HP F9, Lenovo F12), pick the UEFI entry for the stick; check Secure Boot state and that USB boot is enabled. See Create a boot USB for the firmware traps.

PXE network boot stops

Open Console → network boot first. Confirm listening, a ready media set for the PC architecture, the intended deployment interface, and the selected secure/direct mode. The panel's latest diagnosis states the last real client stage and the next check; administrative HEAD probes do not replace that diagnosis.

Before involving firmware, test TCP 8969 from another Windows device on the deployment VLAN:

Invoke-RestMethod http://FORGE-IP:8969/healthz
Invoke-WebRequest -Method Head http://FORGE-IP:8969/boot/amd64/boot.wim

HTTP 200 from /healthz proves the listener and reports which architectures are ready. HTTP 503 proves the network path but means the PXE media is unavailable or invalid. Failure to connect means routing, the selected Forge interface, or TCP 8969/firewall is wrong. Use arm64 in the second URL for an ARM64 client.

1. No request appears: verify wired PXE/IPv4 is enabled in firmware. For another VLAN, relay DHCP to both the lease DHCP server and the Forge. Check UDP 67.
2. proxydhcp is last: discovery arrived but the firmware did not continue. Check UDP 4011, relay/IP helpers, and competing DHCP/WDS boot policies.
3. bootserver is last: the Forge sent the UDP 4011 answer but saw no TFTP request. Check UDP 69, the filename on the client screen, and whether another server supplied options 66/67 or a BOOTP file.
4. tftp-rrq or tftp-failed is last: allow the server-selected dynamic UDP transfer port in both directions. Read the recorded block or client TFTP error instead of retrying a generic timeout.
5. shim-timeout appears: the signed shim completed, but its ipxe.efi request went elsewhere. Empty the normal DHCP ACK's effective siaddr/boot file and options 66/67, and remove competing WDS/PXE responses. Direct mode bypasses this second request only when Secure Boot is disabled.
6. boot.ipxe succeeds: wait through the five-second escape window without pressing Esc. WinPE then starts automatically. If no later asset request appears, retain the client screen and server recent-request entries.
7. http-failed or a partial boot.wim response appears: use its HTTP status and byte count; check TCP 8969, MTU, packet loss, and stateful firewall timeouts.
8. A full HTTP 200 boot.wim completes but WinPE does not open: DHCP, TFTP, iPXE, and the large transfer worked. Focus on wimboot, BCD/boot manager, firmware graphics, the WinPE Secure Boot profile, and the exact client-screen error.

Current secure PXE uses an iPXE v2.0.0 shim rooted in Microsoft Corporation UEFI CA 2011. That trust is independent of PCA2023 WinPE media. A 2023-only firmware trust store must use qualified PCA2023 USB media until a separately trusted PXE first stage is available. See Network boot for the topology, port, filename, and qualification tables.

Direct capture falls back to staging

The client's message includes the server's reason. Checklist: Forge elevated or running as the service; Windows Server service running; TCP 445 open; store disk has room. Staging fallback still works — it just needs local free space on the source machine.

On a domain with hardened NTLM policy, the fallback can trigger with none of the above checklist items actually wrong: direct capture's temporary account is always local, so it only ever authenticates over NTLM, and a GPO restricting incoming NTLM traffic blocks it — usually with a generic logon-failure message, not one that mentions NTLM. See NTLM-hardened domains for why this is expected behavior, not a broken account.

Capture or deploy fails with "not enough space"

• During direct capture: the Forge's store disk is full — move the store to a bigger disk (Storage).
• During staging capture: the source machine lacks local free space — fix direct capture instead.
• During deploy: the target disk is smaller than the image needs.

A deploy is checked for this before the target disk is touched. Two figures matter here and they are not the same number: the size shown in the image library is the compressed WIM, and applying it writes considerably more. A deploy stages that WIM on the target volume and expands it alongside, so the disk must hold both at once — which is why an image can be comfortably smaller than a disk and still not fit on it.

What happens depends on how certain the shortfall is.

Certain — the image file alone is bigger than the volume, so the download cannot even finish. This is arithmetic on two known file sizes, and the deploy stops:

disk 0 is too small for this image: the image file alone is
300.0 GiB and only 199.3 GiB is usable - the download cannot
complete, let alone the install
nothing has been changed - pick a larger disk, or a smaller image

Estimated — it is the expanded size that pushes the deploy over the line. That figure is read from the image's own recorded byte counts rather than guessed, but it can read slightly high for a compressed (CompactOS) source image, so the client warns and lets you decide:

+--[ ! SPACE WARNING ! ]-------------------------------------+
| this image is not expected to fit on disk 0                |
| needs 205.4 GiB (70.8 GiB staged copy + 130.6 GiB once     |
| applied + 4.0 GiB reserve) but only 199.3 GiB is usable    |
|                                                            |
| type CONTINUE to deploy anyway; anything else cancels      |
+------------------------------------------------------------+

Both checks run again against the real partition once it exists, still before the download starts. You are not asked to confirm the same shortfall twice.

If the Forge cannot read an image's expanded size (an unusual or damaged payload), the client says so and checks only the staged copy rather than guessing — it will not refuse a deploy on an estimate it does not have.

Deployed PC demands a Microsoft account

A generalized (Sysprep) image comes up in Windows' out-of-box experience, and recent Windows builds offer no visible way past the Microsoft-account screen once the machine has a network connection.

ImageForge answers those screens for you when the image was captured as a deployment image and a deployment profile is selected at deploy time. Give the profile a local admin account and a locale and setup is skipped entirely — see skipping the out-of-box experience. The deploy screen states which of the two is missing, so check there first if a PC still stops at a setup page.

On a machine already sitting at that screen, press Shift+F10 for a command prompt and run start ms-cxh:localonly to create a local account and continue. (The older oobe\bypassnro command was removed from 2025 Windows builds.)

A replacement clone never shows this: it keeps the source machine's accounts and does not run setup at all. If a clone is asking for a Microsoft account, the source was sysprepped before capture — recapture it as a deployment image.

Long silences

Imaging has legitimately quiet phases: DISM scans files before it has a percent to report, verifies integrity after 100%, and the Forge hashes every byte at finalize. The client keeps its own progress bar or spinner animating through all of these regardless — if that's moving (even just the elapsed-time counter with no percent yet), it's working. A 76 GB image simply takes a while.

Forgot the admin console password

There is no password-recovery email — the Forge runs on your network, not ours. On the Forge computer, open Start → ImageForge → Reset ImageForge Admin Password, approve the Windows administrator prompt, and type RESET.

For a manual or custom-path installation, run this from an elevated prompt in the ImageForge program folder:

cd "C:\Program Files\ImageForge"
imageforge-server reset-admin -data data -restart-service -confirm

This stops and restarts the Forge safely and clears only the admin password. Images, settings, the license, history, and technician access codes are kept. The console then shows the password setup screen. Anyone with administrator access to the Forge computer can do this, so protect that Windows account accordingly.

Reading the audit trail

Console → activity: every capture/deploy with technician, machine (serial/model/MAC), duration, and the failure message when there was one. The failure strings are written to be diagnostic — e.g. DISM capture failed: exit status 112 is disk-full. CSV export at /api/v1/events.csv.

Events are not reaching my RMM/PSA or chat channel

Console → activity → the webhook panel, then send test event. That reports the exact HTTP status the receiver returned, so a broken integration identifies itself instead of looking like an idle Forge — webhooks only fire on completed captures and deployments, so without a test send there is nothing to see until the next imaging job.

The most common failure is the wrong payload format. Slack, Teams, and Discord each require their own message shape and reject anything else — Slack answers HTTP 400 invalid_payload — so a chat webhook left on the default raw format fails every delivery. Choose the matching format in the panel. Full setup, payload reference, signature-verification examples, and per-service notes are in Webhooks & integration.

Waking a machine

Console → activity: any machine with a known MAC address (captured automatically the first time it's imaged) gets a wake button in the fleet table. It sends a standard Wake-on-LAN "magic packet" on the local network — nothing more, since the target has no operating system running yet to talk back to. That means there's no on-screen confirmation the machine actually turned on, only that the Forge sent the packet.

For it to work: WoL has to be enabled in the target's firmware/NIC settings (varies by vendor — look for "Wake on LAN" or "Power On by PCI-E/PCI" in BIOS/UEFI setup), the machine has to be plugged into mains power (WoL doesn't work purely on battery for most laptops), and it has to be on the same network segment as the Forge, or a segment that forwards WoL broadcasts. If your Forge has more than one network interface, set the one facing your fleet under network boot — the wake packet reuses that same setting to make sure it goes out the right one.