Troubleshooting

Start with the session log — the client records everything.

Fast triage

No Forge connectionCheck DHCP, NIC drivers, UDP discovery, manual server address, and TLS pin. Boots vendor recoveryThe USB did not boot. Use one-time UEFI boot menu and check Secure Boot state. Capture falls backCheck elevation/service mode, LanmanServer, TCP 445, and store permissions. Not enough spaceIdentify whether the Forge store, source staging, or target disk is the limit.

Session logs (the black box)

The boot client tees its entire console session — including DISM, diskpart, and network tool output — 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.

Client can't find the Forge

Watch the connect screen — it diagnoses itself in order: waiting for DHCP → borrowing NIC drivers → naming the hardware and what's wrong with it.
"no network hardware detected at all": NIC disabled in firmware, or the dongle/dock wasn't connected before boot.
"network hardware found, but no driver works": use site-specific media with the needed WinPE drivers (see Driver packs). Wireless adapters don't count — WinPE has no Wi-Fi.
"no IP address": adapter is fine — check cable, switch port, and that the network actually has DHCP.
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.
Reaching the wrong/changed server: the TLS pin protects you — compare the fingerprint shown on the client with access → server identity.

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 Boot media 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.

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 its progress bar appears, verifies integrity after 100%, and the Forge hashes every byte at finalize. The client narrates all of these with heartbeat/elapsed lines — if those lines are ticking, it's working. A 76 GB image simply takes a while.

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.