Troubleshooting
Every error
codethe SDK throws or reports, what caused it, and what to change.
JavaScript throws SmongrotError (e.code, e.message). Dart throws SmongrotException (same fields). Catch those two types. A model lookup never throws: lookupModel returns null and, except for "unknown ECU", calls onError.
try {
const s = await connect(transport);
} catch (e) {
if (e instanceof SmongrotError) console.error(e.code, e.message);
else throw e;
}
try {
final s = await connect(transport);
} on SmongrotException catch (e) {
print('${e.code} ${e.message}');
}
Adapter and browser failures sometimes reject with the underlying error and no code (a DOMException from WebSerial, a stream error from fromDuplex). Handle SmongrotError first, then the rest.
Session
ECU_SILENT
No liveness reply after 4 wakes (LOW 70 ms, idle 130 ms, StartComm, three probes). The message is no answer after wake (key ON? cable on the DLC?).
Cause. Key OFF, cable on the wrong plug, wrong serial port, baud not 10400, or a wake the box ignored.
Fix. Key ON. Confirm the port path. See Hardware. Then retry. A Shindengen box just switched to key ON often needs an atomic 70 ms wake (FTDI bit-bang); the Android pulse is about 45 ms and the desktop adapters use an OS break. connect already retries 4 times. That 4 is the default. Call connect again, or pass a higher wakeTries, when you have a reason.
BAD_STATE
The call does not match session.state. The message is session is <state>, needs <state>.
Cause. identify, detect, live or dtc.read while state is not ready. The usual case is calling dtc.read() or a second live() from inside the live loop (state is live). Also: using the session before connect resolves, or after close().
Fix. await connect first. Break the live loop (or abort the signal / cancel the Dart subscription) and wait until it finishes. state returns to ready. Then read fault codes. Do not assign state yourself.
LIVE_UNSUPPORTED
live() probed 0x17, 0x13 and 0x11 and no table returned data.
Cause. The session is up, but this box did not answer a live table. Also a cable that dies after wake, or a table timeout (500 ms) on a very slow link.
Fix. Stay on this session and call identify() — if the ECM-ID arrives, the bus is fine and this box has no level-1 live table (detect() returns null). If the ID is null too, fix the cable and reconnect. Do not fill the screen with zeros.
BAD_PROFILE
live({ profile }) was given an id that is not in the spec.
Cause. A typo, or a liveProfile string from the API that this SDK build does not contain. The API suggestion is often null anyway.
Fix. Omit profile and let live() detect. Valid ids: t17.sub8, t17.sub4, t13.type7, t11.type1, generic.t17.
CLOSED
Any call that talks to the ECU after close().
Cause. A live loop or a late identify still running when you closed, or a second call on the same session.
Fix. Drop the session. connect a new one. close() is final.
NO_WAKE
Cause. JavaScript: the transport has neither wake(lowMs) nor setBreak(on). Dart desktop: the driver refused the break (break on/off refused by the driver).
Fix. Use a shipped adapter, or implement wake (preferred) or setBreak on your transport. A fromDuplex stream needs { setBreak } or { wake } in the options. Passing wake to fromSerialPort uses that instead of the break.
FRAME_NOT_ALLOWED
Cause. Something tried to send a frame that is not in the SDK's read-only allowlist (session start, ECM ID read, keep-alive, live tables, fault-code read). The SDK refuses before anything reaches the cable.
Fix. Nothing to fix in normal use: the public API only sends allowed frames. Writing, erasing and clearing fault codes are not possible through this SDK.
RESPONSE_TOO_LARGE
Cause. The device sent more than 4 KB for a single reply. A real ECU never does this at 10400 baud; it points to a wrong port, a faulty adapter or a device that is not an ECU.
Fix. Check the port and the cable, then connect again.
Adapters
BAD_PORT
fromSerialPort only. The value is not a serialport SerialPort, the baud is set and is not 10400, or the frame is not 8N1.
Fix. new SerialPort({ path, baudRate: 10400, dataBits: 8, stopBits: 1, parity: 'none', autoOpen: false }). Leave baud unset only if you truly have not opened it yet; a wrong baud is rejected.
PORT_OPEN
Dart adapters. Desktop: LibSerialPortTransport.open could not open the path. Android: UsbSerialTransport.open got false from port.open() (permission denied or unplugged).
Fix. Desktop: path from SerialPort.availablePorts, and permission on the device node. Android: call device.create() so the permission dialog can show, then open the port it returns. Plug the OTG cable in before listing.
WRITE_FAILED
Dart desktop only. LibSerialPortTransport.write did not accept every byte (the port write times out at 1000 ms).
Cause. The port stalled or was unplugged mid-write.
Fix. Close, replug, connect again. Android writes do not use this code; a USB error rejects the Future from port.write.
NO_FETCH
JavaScript only, thrown when you create smongrotApi and there is no globalThis.fetch and you did not pass fetch.
Fix. Node 18+ has fetch. On an older runtime, pass fetch in the options. Dart has no such code (http is a real dependency).
API key
These codes are thrown only for NO_API_KEY. Every API_* code is delivered to onError. lookupModel still returns null, and identify() still returns the ECM-ID.
NO_API_KEY
apiKey is missing or blank. Thrown from smongrotApi(...) / SmongrotApi(...), not from identify.
Fix. Pass the key, or do not construct the helper. Without a helper, connect without lookupModel and model stays null. Get a free key at https://developers.smongrot.com.
API_BAD_INPUT
onError. The string passed to lookupModel is not 10 hex characters after spaces are removed and letters upper-cased.
Fix. Pass identity.ecmId, which is already 10 upper-case hex, or do not call lookupModel when ecmId is null.
API_UNAUTHORIZED
onError. HTTP 401 or 403.
Fix. The key is wrong, or it was stripped of the Bearer scheme. The helper sends Authorization: Bearer <key> itself. Pass the raw key, not a header.
API_RATE_LIMITED
onError. HTTP 429. The free key allows 1000 requests a day.
Fix. Cache the model for that ECM-ID in your app. Live data does not call the API. identify() caches too: one session looks up once.
API_NETWORK
onError. The request threw, or hit the timeout (default 5 s, timeoutMs in JS, timeout in Dart).
Fix. Offline is a supported state. Show the ECM-ID and leave the model as —. Raise timeoutMs only if your network is slow. Do not retry in a tight loop.
API_ERROR
onError. Any other HTTP error. e.message includes the status and the API's error.code / error.message when the body has them.
Fix. Read e.message. The ECM-ID read from the box is still valid.
API_BAD_RESPONSE
onError. HTTP 200 but the JSON has no usable data (model, ecu_code or maker).
Fix. Treat it as an unknown model. Do not parse the body a second way; modelInfoFromApi is the parser.
Unknown ECU
HTTP 404 returns null and does not call onError. The box is simply not in the catalog. Show the ECM-ID.
Timeouts, NAK, echo
These are not error codes.
Timeouts. A command read stops after 120 ms of silence or 2000 ms. A live-table read stops after 120 ms of silence or 500 ms. Nothing is thrown. You get a short or empty reply: fields come back absent, or dtc.read() comes back failed. Fix the cable and the key before you touch timing. Override commandTimeoutMs / tableTimeoutMs (JS) or the matching Timing fields (Dart) only for a link you have measured as slow.
NAK. A fault-code reply that contains the byte 0x7F counts as no answer. If all three 72 05 74 reads are silent or NAK, outcome is failed. The SDK does not invent codes from a NAK. Reconnect with the key ON. Do not clear codes; v0.1 has no clear call.
Echo. The session strips the echo of every frame it sends; you never handle it yourself.
echo |
distorted |
What happened |
|---|---|---|
true |
false |
The cable echoed the request exactly. Normal. |
true |
true |
The echo only cleared bits (never set them) and a valid reply follows. Some USB cables do this. The reply is still used. |
false |
false |
The read-back did not start with the request. Wrong baud, a port that was not flushed, or two sessions on one cable. |
distorted: true once in a session is not a failed read. echo: false plus an empty reply is the same symptom as ECU_SILENT: fix the port settings (10400 8N1, no flow control) and use one session.
Symptoms that look like bugs
Rpm is 0, or a huge number like 17,500, and temperature is −30 °C. The engine is off (key ON). Check frame.engine === 'off' (injector 0 ms and ignition 0°): rpm and temperature are then not real values. Show "engine off". A missing rpm (no table) is absent; show — for it.
Battery looks fine, other values are absent. Check frame.profile.
generic.t17has onlyrpm,tps,inj_ms,ign. No temperature, no battery.- Shindengen (
t17.sub4) reportseot, notect. Looking upecton that profile is alwaysabsent. o2ris on a secondary table polled every 5 ticks, and given up after 3 misses. The first frames do not have it.- Shindengen
battis provisional. Raw0isabsent, not 0.0 V. The extra battery source is polled every 10 ticks, except ECM-ID0105950D01, which is read from the primary table. primaryOk: falseclears the primary fields for that frame. Do not keep the previous numbers.
Shindengen, key just turned ON, connect fails or takes several tries. The 70 ms wake has to be timed on the adapter. An OS break sometimes misses, and the Android ~45 ms pulse is specified as ignored by a Shindengen box fresh off key ON. Let the 4 retries finish. If it still throws ECU_SILENT, use an FTDI cable and pass an atomic wake / atomicWake that holds the line LOW for the lowMs you are given (70 ms). connect already wakes; an extra pulse before it only adds jitter.
model is null. No lookupModel was passed, the key was rejected, the network failed, the daily limit was hit, or the ECU is unknown (404). id.ecmId is still the value from the box. Read onError to see which of the API_* codes it was. 404 is silent.
The browser has no navigator.serial. WebSerial is desktop Chrome or Edge, in a secure context, called from a click. Firefox, Safari and phone browsers do not implement it. Use Node or the Flutter adapters.
Android listDevices() is empty. The cable is not OTG, the plug is charge-only, or the phone is not in USB host mode. Re-list after the permission grant. create() returns null when the user denies it: that is PORT_OPEN only if you open a null port; check for null first (the example does).
Next: FAQ