Skip to content

Troubleshooting

Jump to bottom
Quadstronaut edited this page Jul 28, 2026 · 1 revision

Troubleshooting

Installation issues

TypeError or crash on first keypress

Cause: The upstream pydirectinput package is installed instead of the required pydirectinput-rgx fork. The upstream package lacks scancode_keyDown / scancode_keyUp.

Fix:

pip uninstall pydirectinput
pip install pydirectinput-rgx
ed-autojump doctor   # verify: pydirectinput check should show PASS

doctor reports FAIL binds_preset — missing critical bindings

Cause: The bundled ED-AFK.4.2.binds file is missing or corrupted, or a required action (Hyperspace, SetSpeedZero, SetSpeed25, SetSpeed50, SetSpeed75, SetSpeed100, PitchUpButton, PrimaryFire) is not bound.

Fix: Reinstall the package in editable mode:

pip install -e .[dev,hotkey,vision]
ed-autojump install-binds

doctor reports WARN pydirectinput — not importable

Cause: pydirectinput-rgx is not installed. The bot can run in record-only mode but cannot send keys.

Fix: pip install pydirectinput-rgx (or pip install -e .[dev,hotkey])

doctor reports WARN panic_hotkey — no global hotkey backend

Cause: The keyboard library is not installed. Ctrl+Alt+P will not work.

Fix: pip install -e .[hotkey] — Ctrl+C in the terminal still trips the panic switch.

Vision / compass issues

Bot runs but does not orient the ship before jumping

Cause: Vision is not enabled or the compass is not calibrated.

Fix:

  1. Get into the cockpit with the nav compass visible.
  2. Run ed-autojump calibrate-compass — wait for the 3-second capture.
  3. Paste the printed [vision] block into config.toml.
  4. Verify [vision].enabled = true in config.toml.

vision deps missing when running calibrate-compass

Cause: The vision extra is not installed.

Fix: pip install -e .[vision]

Screen capture returns no frame

Cause: The gdi backend (default) failed, or you opted in to dxcam/dxcam-cpp and it does not work on this machine (returns a black frame on some setups).

Fix: If you switched to dxcam, revert to the default in config.toml:

[vision]
capture_backend = "gdi"

Bot orients but FSD charge keeps cancelling

Symptom: orient_compass succeeds, engage_jump fires, but the charge drops repeatedly.

Cause: The coarse compass alignment tolerance (align_tol) is loose by design (default 0.20) — the widget-ring fine pass is what owns jump-time precision. If the widget pass is off or missing, the ship can be at the edge of the FSD cone when it tries to charge.

Fix: Keep the widget-ring fine pass enabled (it does the precise alignment). If you must run compass-only, tighten the coarse tolerance:

[vision]
align_tol = 0.12   # tighter than the 0.20 default; only needed when running compass-only

If the problem only happens with the widget-ring fine pass, check that the HUD mouse widget is enabled in Elite's settings in "point" mode.

Bot HALTS at launch: HALT: mouse widget not detected

Symptom: With --engage-keys, the run stops immediately at preflight with a loud banner and return code 3, never entering the loop.

Cause: [vision].widget_ring_on_miss = "required" (the default) makes the HUD mouse widget mandatory. If it is not detected at launch, the bot refuses to fly — a deliberate guard: with the loosened align_tol, flying compass-only would leave every FSD engage misaligned.

Fix: In Elite Dangerous, enable the HUD mouse widget and set it to "point" mode (it is in the bundled ED-AFK preset), then relaunch. If you genuinely cannot use the widget, change the miss policy:

[vision]
widget_ring_on_miss = "degrade"   # skip the fine pass, jump compass-only
# or
widget_ring_alignment = false     # disable the fine pass entirely

WARNING: mouse widget not detected (degrade / fail_closed modes)

Cause: The widget-ring fine alignment pass cannot detect the HUD widget, and widget_ring_on_miss is set to "degrade" or "fail_closed" rather than the default "required".

Fix: Enable the HUD mouse widget in "point" mode. The three miss policies:

[vision]
widget_ring_on_miss = "required"    # DEFAULT — halt at launch until the widget is visible
# widget_ring_on_miss = "degrade"   # skip the fine pass, jumps proceed compass-only
# widget_ring_on_miss = "fail_closed"  # fly but never jump until the widget is detectable

CV debug boxes do not appear (or are offset from what they target)

Symptom: You expected the labeled CV/OCR boxes (green hit / red miss) over the compass, nav-panel rows, etc., but see nothing — or they draw in the wrong place.

Causes and fixes:

  1. cv_debug is off (the default). The boxes are opt-in. Turn them on via the launcher VISION toggle (which persists ED_AUTOJUMP_OVERLAY_CV_DEBUG=1 to projects/ed-autojump/.env), or set cv_debug = true in config.local.toml. On startup, run prints exactly one CV-debug ON/OFF line — check it says ON.
  2. EDMCOverlay is not running / the overlay is disabled. CV boxes are fail-soft: no EDMCOverlay server or [overlay].enabled = false means no boxes. The overlay only draws while Elite is the focused, foreground window.
  3. Boxes appear but are offset from their targets. The screen→overlay transform is untuned. Run ed-autojump calibrate-overlay. On startup with CV boxes on, run also flashes a self-test: a GREEN "RAW" rect and a RED "TRANSFORMED" rect. Seeing both = transform OK; RAW only = run calibrate-overlay; neither = EDMCOverlay is not rendering rects.

Journal / status issues

doctor reports WARN status_files — missing in journal dir

Cause: Status.json or NavRoute.json are not present — the game likely has not run yet in that journal directory.

Fix: Start Elite Dangerous and let it reach the main menu. The files are created on launch.

doctor reports FAIL journal_dir — does not exist

Cause: The journal directory does not exist at the expected path.

Fix: Set the correct path in config.toml:

[paths]
journal_dir = "%USERPROFILE%\\Saved Games\\Frontier Developments\\Elite Dangerous"

Or pass --journal-dir <path> on the command line.

Launch / game automation issues

--launch failed: MinEdLauncher.exe not found

Cause: MinEdLauncher is not on PATH and not at auto-detected locations.

Fix: Pass the explicit path:

ed-autojump run --launch --mel-path "C:\path\to\MinEdLauncher.exe" ...

Or set in config.toml:

[launcher]
mel_path = "C:\\path\\to\\MinEdLauncher.exe"

--launch failed: LOAD_GAME_TIMEOUT

Cause: The game did not emit a LoadGame journal event within launch_timeout_s (default 120 s). The game may be slow to load or stuck on a dialog.

Fix:

  • Increase the timeout: [launcher].load_game_timeout_s = 180.0
  • Enable dismiss_dialogs = true (default) to auto-dismiss update/EULA dialogs.

Menu navigation sends keys to the wrong window

Cause: The Elite window is not in focus when menu navigation starts.

Fix: Ensure launch.ps1 focuses the Elite window (the 5-second countdown), or call ed-autojump run --launch which focuses the window before menu navigation. Pass --engage-keys — without it, menu navigation uses NullSender and sends nothing.

Runtime / flight issues

Ship does not move — bot starts but nothing happens

Cause: No hyperspace route is plotted in-game and --route-plot is not active. The bot waits for a route to follow.

Fix: Plot a route in the Galaxy Map, or add --route-plot to auto-plot via Spansh:

ed-autojump run --engage-keys --route-plot --duration 21600

Bot keypresses land in the terminal, not in Elite

Cause: Elite Dangerous is not the focused window when key dispatch starts.

Fix: Use launch.ps1 (it runs a 5-second countdown to give you time to click Elite). Or with the CLI, use --engage-keys — the bot calls focus_ed_window() automatically before the first keypress. If the focus call fails, a WARN is printed and you must click the Elite window manually.

Panic hotkey does not work (Ctrl+Alt+P)

Cause: The keyboard library is not installed (hotkey extra missing) or another application has registered the same hotkey.

Fix: pip install -e .[hotkey]. Ctrl+C in the terminal always works as a fallback.

procedure error: unknown action <name> on startup

Cause: A procedure TOML file references an action name that does not exist in the step library.

Fix: Check the procedure file against the action names in procedures/procedures.md. The loader validates all procedures at startup and refuses to run rather than improvise.

Bot aborts mid-session with required step failed

Cause: A step marked required = true failed (e.g., vision alignment timed out, danger-class star detected, FSD blocked). The procedure ran its retry/abort policy.

Fix: Check the session JSONL for the outcome row that shows which step and why. Common causes:

  • Alignment timing out: compass may have drifted off the calibrated region — recalibrate.
  • Danger-class star: the in-game route includes a system whose star is in the danger list; the bot correctly refuses to jump. Replot the route to avoid it.
  • FSD blocked: the ship may be mass-locked, docked, or overheating.

Session recordings

How to view a session JSONL

Each line is a JSON object. Use python -c "import json,sys; [print(json.dumps(json.loads(l), indent=2)) for l in open(sys.argv[1])]" session.jsonl | head -100 or any JSON viewer.

How to anonymize a session before sharing

python -m ed_core.anonymizer session.jsonl session-anon.jsonl

Replaces Commander, FID, and AccountID fields. System names and timestamps are left intact.

Connection-error recovery (server drops)

When Elite's servers drop, the game throws a full-screen CONNECTION ERROR dialog. The real-time monitor detects it (OCR) from any scene and runs connection_recovery: press OK → main menu → Continue → Solo (automatons can't play Open) → load into normal space → re-plot the last route via the galaxy map.

Warning

Known limitation (2026-07, awaiting training frames): recovery may FAIL on the first attempt. After Continue, the game-mode buttons (Open / Private / Solo) stay grayed out and non-responsive until the client re-authenticates with Frontier's servers. The macro's timing is not yet trained on that grayed→ready transition, so a too-early Solo press is a no-op. The real-time monitor keeps watching, so a later attempt (once the servers answer) usually succeeds — but expect one or more failed passes on a cold reconnect. A CV detector for the enabled-vs-grayed button state is stubbed and will be trained once operator frames are available.

Clone this wiki locally