Troubleshooting¶
Find your symptom in the list below. Each entry gives the likely cause and the next step.
Start with these two commands. They answer most questions:
canair status # what am I talking to, and does it work?
canair logs # transport drops, timeouts and decode failures
The device is not reachable¶
Symptom: canair status exits with code 1, or a live command cannot connect.
- Check that the dongle has power. Switch the car to ignition or accessory mode.
- Check that your computer is on the right network. In access-point mode, join the
WiCAN_xxxxnetwork. The dongle is then at192.168.80.1. - Check the address with
canair config. To change it, runcanair config set devices.home.host <ip>. - If you have several devices, canair tries the others when the chosen device is down. Run
canair status --no-fallbackto check only the chosen device. - If the dongle needs time to appear, add
--waitto the command.
See Connect your dongle.
canair status exits with code 2¶
Exit code 2 means that the configuration cannot work. Common causes:
- You use a
wican-wstransport withwican_model: classic. A classic WiCAN has nowican-ws. Useslcan-tcp. - You use
wican-wson WiCAN firmware v6. v6 has no/wsterminal. Useelm327-tcp.
The status output names the cause and the fix. See
Firmware compatibility.
Every ECU looks dead on firmware v6¶
Cause: The slcan-tcp transport on a stock v6 device accepts the connection and then discards
everything.
Fix: Either switch to elm327-tcp on port 35000, or enable socket_manager, bridge_manager
and can_manager on the device. See
Firmware compatibility.
discover finds no ECUs, or too few¶
- Switch the car to ignition or accessory mode. Sleeping ECUs do not answer.
- Run the sweep again with a longer pause:
canair discover --delay 0.5. - Ask one ECU directly:
canair raw ECU:3E00. An ECU can ignore a broadcast request and still answer a direct request. - On a car with a central gateway, check which buses you can reach from the port:
canair discover --functional. - If you use a generic ELM327 clone, try a WiCAN. Clones often fail on newer vehicles that use long multi-frame ISO-TP or 29-bit addressing.
See Discover ECUs.
An ECU answers, but a read fails or returns nothing¶
- The ECU needs an extended session. Add
--sessiontoread,scanoridentity. - The ECU is asleep. Add
--wake. - The ECU answers this PID only in another vehicle state. For example, a body module may answer only with the ignition on. Change the state and try again.
- The ECU answers with a negative response code (NRC). The NRC tells you why. For example,
requestOutOfRangemeans that the ECU does not know this PID.canair bix --annotate PAYLOADdecodes the NRC.
A read is slow, flaky or truncated¶
- Run
canair logs. Look for dropped frames, stale replies and timeouts. - If you use a generic ELM327 clone, the adapter is the likely cause. Try a WiCAN.
- If the link is slow (VPN or cellular), use
--transport wican-wson a WiCAN Pro. It keeps the ISO-TP flow control on the car side of the network. See Remote & cellular links. - For a long recording, add
--wait. The monitor then reconnects after a drop and continues the same recording.
In the monitor, a PID that stops answering is polled less often until it answers again. The row
says slow (not answering).
Another session holds the connection¶
Symptom: A command says that another canair session holds the device connection.
The device serves one connection at a time. Run these commands in order. Stop when the problem is gone.
canair lock # who holds the connection?
canair lock steal # ask that session to release it, then wait
canair lock kill # signal a session that does not respond (asks first)
A command with --force asks the other session to release the connection, and then continues.
canair never kills another process without your confirmation.
canair asks me to choose a profile or a variant¶
- If you have more than one profile, canair does not guess. Pass
--profile NAME, setCANAIR_PROFILE, or runcanair profile use NAME. - If a profile covers several variants of a car, canair does not read or record data until you
name yours:
canair profile use NAME --variant VARIANT. Runcanair variantsto see the options.discoverandidentitywork before you choose, because you use them to find out.
My captures or edits disappeared after an update¶
Cause: You wrote to a bundled profile with a bare canair that you installed with
uv tool install. That copy of the profile is frozen. A reinstall replaces it.
Fix: Keep your data outside the snapshot. Either run
canair config set profiles_dir /path/to/canair/profiles, or run
canair profile adopt PROFILE to take your own copy. See
Point your writes somewhere durable.
If a recording session crashed, recover its data with canair captures uds --recover.
canair shows an old version or old behavior¶
You may have two copies of canair. A bare canair runs the installed snapshot. uv run canair
runs the code in your checkout. Run canair --version to see which copy runs. See
The two installs can drift out of sync.
A feature is refused as Pro-only¶
You set wican_model: classic, or the device is a classic WiCAN. AutoPID device sync,
wican mode set and the wican-ws transport need a WiCAN Pro. Everything else works on both
models. See Pro vs. classic.
Still stuck?¶
- Run
canair status --jsonandcanair logs -n 200. - Open a GitHub issue and add the output. Remove any VIN first.