Troubleshooting

Rule of thumb: nexus doctor first — it reports 19 diagnostic categories
with suggested fixes and is the same gate the engine runs pre-launch.

Engine refuses to start

Symptom	Likely cause	Action
"MT5 terminal missing/not running"	terminal closed / not installed	start MT5, log in (demo first), retry
config validation error	YAML contract violation	`nexus config --validate <path>`; fix the named key
environment blocked (exit 3)	Windows ARM64	unsupported by dependency stack; use x64
migration gate failure	schema drift	`nexus db migrate`; check `nexus db hygiene status`

Symptom	Likely cause	Action
dashboard unreachable	port drift (dev UI/API ports can move)	check `nexus status` output / launcher log for the bound port
"Cannot GET /" on some port	wrong port — something else is listening	use the port from `nexus status`
SSE not streaming	proxy buffering	connect directly to `127.0.0.1:<port>`

Symptom	Meaning
orders rejected at broker	"Allow Algo Trading" unchecked in MT5 options
SAFE_MODE after rejections	circuit breaker tripped (3 rejections) — inspect `nexus incidents` + `/api/debug/trace`
no trades for long periods	check regime gate + confidence gate in the debug console; counterfactual evidence shows the confidence gate often filters losing trades — silence can be correct behavior

Symptom	Meaning
`SCALER_MISMATCH` / `MODEL_INPUT_DIMENSION_MISMATCH`	bundle doesn't match the active feature schema — the load gate is doing its job; don't bypass it
`FEATURE_CONTRACT_MISMATCH` SKIP in logs	retrain record refused (invalid snapshot) — by design, never zero-filled

Symptom	Meaning
`RELEASE_NOT_FOUND`	no release exists yet — honest state, not an error
`NO_UPDATE`	you are current
update refuses to run	engine is LIVE — updates are blocked while LIVE by contract

nexus export-diagnostics produces a sanitized ZIP (secrets redacted by

contract). Attach it to an issue — never paste raw logs with credentials.