| name | luxonis-troubleshoot |
| description | Diagnose a broken or incorrect existing OAK or DepthAI application. Use when an existing app fails, hangs, or gives wrong output. |
Luxonis Troubleshoot
Restore an existing OAK path. Change one cause, rerun the same observation, and stop at the
first failing layer.
Done when
The original failed observation passes and the next dependent check still works, or blocked
with a named next action. Hardware fault (orange LED, boot failure, suspected calibration)
goes to support@luxonis.com.
Never invent DepthAI APIs from memory. DepthAI v3 only; do not mix v2 APIs.
Best source first: the Luxonis MCP tools (surfaced names vary by host), then the exact example
or doc source they return, then https://docs.luxonis.com/llms.txt, then observed behavior;
memory is only for general reasoning. For oakctl commands and flags, the installed
oakctl --help outranks docs and MCP: the local version (possibly older or beta) defines what
is possible here, so work from it and suggest an oakctl update when it lacks something current
docs describe. If observed host or device behavior contradicts docs or MCP, trust the
observation and note the conflict. If offline, work from oakctl --help and local examples and
name which facts are unverified.
If AGENTS.md is missing, or oakctl is missing when this job needs the host toolchain, name
luxonis-workspace and follow it, then continue. Do not copy its procedure.
Read docs/brief.md, docs/device.md, source, logs, and evidence when present. Also read
legacy root PROJECT_BRIEF.md and DEVICE.md if present. None is required. Treat
docs/device.md as setup notes; trust live state. Do not start a greenfield interview. If
the product is wrong, mention luxonis-app.
1. Freeze one failure
State one expected observation and the smallest actual result that contradicts it. Preserve
the exact run and observation commands, the device used in this reproduction, topology,
representative input, relevant versions, and complete stderr, frame, or consumer output when
obtainable.
Reproduce once before editing when safe and bounded. For an intermittent failure, collect
several bounded observations and record frequency.
2. Locate the first failing layer
Check in order and stop at the first failure:
- Host toolchain and imports.
- Device discovery, transport, power, and exclusive access.
- Host process or OAK App lifecycle.
- Pipeline construction, links, registration, and topics.
- Sensor or replay input.
- Model/archive input, preprocessing, parser, and inference.
- Synchronization, crops, tracking, geometry, and application state.
- Requested file, MQTT, API, UI, terminal, or other final output.
If the device path is unverified, use luxonis-device-setup. To capture or replay a
holistic recording, use luxonis-record. For claims about live frames, detections, depth,
crops, tracks, or structured pipeline messages, use luxonis-inspect. Verify external
output separately from pipeline evidence.
A cheap split: can a minimal known-good DepthAI snippet open the device and stream one frame?
If that fails, the layer is device/connection. If it passes, bisect the app against the
closest current example.
Crash/error: rerun under DEPTHAI_LEVEL=debug. Bad depth or output: capture a frame. Low FPS:
measure a number.
3. Test one hypothesis
Explain why current evidence favors one cause and what result would falsify it. Change one
cause. Keep the reproduction and observation commands stable. Retry an unchanged action no
more than twice; a third attempt needs a new hypothesis or a human decision.
Prefer a bounded repair: align the environment with the selected example; correct one
address, endpoint, queue, topic, link, or blocking read; restore archive input, parser, or
label order; use the same filtered detections for dependent tracking and crop paths.
Do not begin with a broad rewrite, model replacement, device update, or topology change.
4. Verify the repair
Rerun the original failed observation. If it passes, rerun the next dependent check so a
local fix does not hide a downstream regression. Report root cause, evidence, changed files,
exact before/after commands, passing checks, and remaining unverified claims.
Guardrails
- Ask before sudo/admin, firmware/OS updates, flashing, factory reset, Hub adoption,
persistent networking, global pip, or replacing customer artifacts.
- Never compile DepthAI from source.
- Do not pretend WSL has USB.
- Never run competing processes against one device.
- Training, proprietary SLAM, or a complete ROS system: say so and stop. Do not call the OAK
use case impossible. State what stays human-owned and one next step.
