Troubleshooting

"Scan hangs 30s on launch"

Fixed in v45.1.23. Before v45.1.23 the scan-start path blocked the Python event loop on a synchronous DNS lookup for the target hostname. On slow-DNS networks the sidecar appeared to freeze for ~30 s. The fix moves the lookup onto a worker thread. If you see this behaviour, upgrade to v45.1.23 or newer.

"LicenseStatusBadge empty" / header badge blank

Fixed in v45.1.24. A CSS regression in v45.1.22 hid the license badge contents. v45.1.24 restores it: the header now shows the mode (Development / Licensed / Unlicensed), company name, and active module chips.

"Window won't close" / close + minimize buttons do nothing

Fixed in v45.1.23 (handlers wired) and confirmed working in v45.1.24. The frameless-window close and minimize controls were silent no-ops before v45.1.23 because the IPC channels were declared but never handled in main. If you're on v45.1.22 or earlier, upgrade. As a stopgap on older builds, use Alt+F4 (Windows) / Cmd+Q (macOS) / close via the taskbar.

"Tool X not found" (adb, nmap, apktool, …)

Handled by bundled-helper PATH integration when available. If the error persists:

1. Verify your current build actually shipped the helper bundle — check Settings → Health → Diagnostic Logs for a line beginning "[bundled-tools] PATH prepend: …". If you see "No bundled-tools directories found on disk", this build is relying on the system PATH or the install is incomplete.
2. Check antivirus quarantine — some AV products quarantine bundled binaries as "unknown publisher". Restore them and add the install folder to AV exclusions.
3. Install the tool manually at OS level as a fallback — winget install Nmap.Nmap / apt install nmap android-tools-adb. PhantomYerra will pick up the system-installed copy via PATH.
4. If the problem persists, email phantomyerra@coesecurity.com with the "Tool X not found" error and the diagnostic log line.

See Bundled Tools on Install for the current bundled-helper policy and PATH behavior.

"403 — target not in license scope"

Expected behaviour from v45.1.23 (Layer 3 scope patterns). Your license carries allow/deny patterns; the target you tried to scan doesn't match. The banner shows the exact allowed patterns. Contact your license administrator to add the target; no restart required — the client picks up the new patterns on the next license poll (~5 min). See License Scope Patterns.

"Attack Graph stays empty during a scan"

Fixed in v45.1.24. The live WebSocket stream to the graph panel silently 404'd in v45.1.22/23 builds. v45.1.24 restores live streaming — nodes and edges draw as findings correlate in real time. The panel header shows ● Live when connected, ○ Offline when reconnecting.

"NameError: x" in a report or scan event

This indicates the Python obfuscator renamed a variable that shouldn't have been renamed. Upgrade to the latest build (the build smoke test now runs 553 modules through import to catch regressions). If the error still appears:

1. Collect the diagnostic bundle from Settings → Health → Collect Diagnostic Bundle — it includes the obfuscator debug map.
2. Send the bundle + the exact error message to phantomyerra@coesecurity.com.
3. As a temporary workaround, retry the operation — most NameErrors are in code paths that recover gracefully on the next event.

"Playwright Not Installed"

Fixed in v45.1.21+. Playwright Chromium is now auto-installed on first use. If the error persists on a fresh install, it's because the packaged Python environment hasn't been primed yet — launch PhantomYerra once to trigger the auto-install hook. The hook is idempotent; subsequent launches are instant.

Manual fallback: from the app directory run python -m playwright install chromium. On Linux, also install libnss3 libatk-bridge2.0-0 libxkbcommon0 libgbm1.

"Sidecar offline"

The Python scan engine sidecar takes 3-8 seconds to come up. If it's still offline after 60 seconds:

• Open Settings → Health → Restart Sidecar. The button kills the process, unlocks the DB, respawns with the correct -OO optimization flag.
• Check %APPDATA%\PhantomYerra\logs\sidecar.log (Windows) or ~/.config/PhantomYerra/logs/sidecar.log (Linux) for the last traceback.
• If Windows Defender quarantined a module, add the four folder exclusions (see the installation guide).

"License validation failed"

The app contacts the PhantomYerra license server at launch. If validation fails:

• Confirm internet connectivity — the app will not run without a valid license.
• Corporate proxy? Set proxy env vars before launch: HTTP_PROXY, HTTPS_PROXY.
• Time-skew? The license validator rejects a system clock more than 5 minutes off true UTC. Fix NTP.
• Check license status at Settings → License for the server's exact error reason.

"Scan finds nothing"

When a scan completes with zero findings, the cause is almost always one of:

• Scope too narrow: the wizard excluded authenticated endpoints. Re-run with credentials.
• Auth not configured: without valid auth, 90% of an authenticated API's attack surface is invisible. Use the Auth step in the wizard.
• Intensity too low: default intensity is Balanced. Increase to Thorough for a first assessment; Aggressive only in contract-allowed lab scope.
• Target is genuinely clean: rare on real enterprise targets, but possible on a single-page static site.

"Report export 404"

Fixed in v45.1.21. The download URL was mapped to a route that didn't exist in the packaged build. Upgrade to v45.1.21+ and the report export works end-to-end.

"CLI terminal garbled"

Fixed in v45.1.21. The CLI no longer emits raw ANSI escape sequences to Windows cmd.exe without Windows Terminal; detection + fallback is automatic. If on a legacy terminal, run with --no-color or pipe through more.

"Engine crashed — UnboundLocalError"

Fixed in v45.1.22. Root cause was the Python obfuscator's variable-scope pass incorrectly renaming a closure variable. The fix tightens visit_Nonlocal / visit_Global and verifies every module still imports after obfuscation (build smoke test runs 553 modules). Upgrade to v45.1.22+ to eliminate.

"btoa InvalidCharacterError"

Fixed in v45.1.22. The renderer's evidence hash utility used the browser btoa() on a UTF-8 string containing non-Latin-1 bytes. The fix switches to a Unicode-safe SHA-256 path (TextEncoder + SubtleCrypto). Unicode file names, target URLs with IDN, and non-ASCII payloads now hash correctly.

Sidecar port conflict

If another service already binds 127.0.0.1:8731, the sidecar fails to start. Fix by closing the conflicting service or by setting PHANTOMYERRA_SIDECAR_PORT=8732 in the environment before launch. The renderer picks up the override automatically.

Still stuck?

Every crash emits a scrubbed field report (PII-free) to the PhantomYerra triage pipeline automatically. If a crash happens twice, it's already on the triage list. To manually capture logs for support: Settings → Health → Collect Diagnostic Bundle, then email the bundle to phantomyerra@coesecurity.com with a short note describing what you were doing when the error occurred.