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\.

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": copy the exact signed package named by the logged hardware ID into the architecture-specific boot-driver depot and rebuild, or connect the site's certified USB Ethernet adapter. Wireless adapters don't count — WinPE has no ordinary Wi-Fi path.
4. "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.
5. 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.
6. Reaching the wrong/changed server: site-pinned media rejects a different TLS fingerprint. Unpinned media requires the technician to compare and enter the complete 64-hex-character SHA-256 fingerprint shown on the client with access → server identity before an access code is sent. This is a one-time step per Forge per stick: a verified fingerprint is saved to \ImageForge\known-forges.txt on the boot USB and trusted automatically on later boots (delete that file to force re-verification). Colons are optional when typing, and a rejected entry says why — too few characters, a stray non-hex key, or the exact position of the first mismatched character.

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.

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.

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. Recovery instead uses local access to the Forge machine itself. From an elevated prompt on that machine:

cd "C:\Program Files\ImageForge"
imageforge-server reset-admin -data data
imageforge-server stop
imageforge-server start

This clears only the admin password — technician access codes are kept. After the restart, the console shows the first-run setup screen where you set a new password. Anyone with administrator access to the Forge machine can do this; that's the same trust boundary as the data directory itself, so protect the machine 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.

Sending events to your RMM/PSA

Console → activity → the webhook panel. Enter the URL your RMM/PSA (or a simple Slack/Teams/Discord incoming webhook) gives you and save — every capture/deploy fires a POST there with the same JSON as the audit trail, moments after it happens. Enabling generates a signing secret shown once; copy it immediately, since the console only ever shows whether one is set afterward, not the value. If a receiver needs re-pointing or the secret may have leaked, regenerating issues a new one and immediately invalidates the old one.

Each delivery carries an X-ImageForge-Signature: sha256=<hex> header: an HMAC-SHA256 of the exact request body using your secret. Verify it on your receiving end before trusting the payload — recompute the HMAC yourself and compare. A delivery that fails (timeout, non-2xx) retries a couple of times automatically, then gives up; the audit trail itself is unaffected either way, since the webhook is a notification on top of it, not a replacement for it. The panel's recent-deliveries list shows the last few attempts and their status, which is the first place to check if events aren't arriving.

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.