Troubleshooting
Start at the failing step and proceed only after the earlier step works.
| Symptom | Start here |
|---|---|
| Installation fails or the web page does not open | Installation |
| The page opens but never becomes ready | Connection |
| Ready, but no messages | Delivery |
| Device missing or LED unchanged | Device control |
| Duplicate messages after navigation or reconnection | Duplicates |
| After another connection logs in with the same credentials, the old one drops and does not reconnect | Duplicate logins |
1. Installation and startup
For the web chat examples in the iosignal-examples repository:
- Check
node --versionandnpm --version. Use Node.js 22.16 or later and check the example'senginesrequirement. - Open the example folder containing
package.jsonandpackage-lock.json, not the repository root. - Run
npm ci. Distinguish network/proxy failures from lockfile mismatch. Record the downloaded revision and error; do not delete the lockfile as the first fix. - Run
npm run dev. If you seeEADDRINUSE, stop the process already using the port or update matching server/client settings. - Open the web URL,
http://localhost:5175for Vanilla, not the WebSocket URL.
For Node-module errors in browser builds, check that you import the browser entry point iosignal/browser/esm/io.js.
2. Connection never becomes ready
- Ensure the IOSignal server is running. The quickstart requires a separate server; example
devstarts one, whilepreviewrequiresnpm run serverseparately. - Match the server URL: quickstart WebSocket port is 7777; Vanilla chat WebSocket port is 7779; its web page uses 5175.
localhostmeans the machine running the client. Use the server's LAN address or domain from another device, and check its listening address and firewall.- HTTPS pages need a trusted TLS-enabled WSS endpoint. Changing
wstowssalone does not configure TLS. - Inspect browser Console and Network errors for certificates, authentication, refused connections, and local-network permissions. Compare credentials with server configuration without logging secret keys.
More detailed connection and server authentication guides cover deployment configuration.
3. Ready but no message arrives
- Connect sender and receiver to the same server. Framework examples use different ports.
- Match tags exactly, including case and
#,@,$. The chat usesopenchat; quickstart useshello#message. - Subscribe before sending to ordinary channels. From 9.6.0,
listen()auto-subscriptions are sent before the ready event. With manual subscriptions, callsubscribe()thensignal()inside ready. Clients at 9.0.x or earlier send auto-subscriptions after ready handlers, so check the version. - Send direct messages to the recipient CID and handle
@or@topic. Do not wait for direct messages inmessageor callsubscribe('@topic'). - Inspect received tag and data. If data arrives but the UI stays unchanged, check the handler and state update. A sender log does not prove delivery or command completion.
HOME CHANNEL tags also require matching home-channel scope. See tags, payloads, and subscription order.
4. Device discovery or output fails
- Wait until the board's serial monitor shows it is connected and prints its CID. Check Wi-Fi first. Arduino TCP host settings do not include
ws://. - Confirm the web client and board use the same server. WebSocket and TCP ports can differ.
- Look for a device card in Remocon. With the CLI, subscribe to
#notify, send#search, and look for a CID or group channel. Confirm HOME CHANNEL scope and that the sketch answers#search. If you know the serial CID, subscribing todeviceCID@$nameanddeviceCID@$uidirectly separates discovery from device-info problems.$nameisnameorname:category;$uiis a button list (ON,OFF) or a value starting witht=,p=orv=, such ast=light.1. The type must be listed at device types (such aslight.1). See Build a device (app.iosignal.net compatible) for the rules. - Use the device CID, not the web client's CID. Anonymous clients can receive a new CID after reconnecting. After handling a command the sketch must send
@$state, even for an unknown command, or the app keeps waiting. - Compare reported state and actual LED output. Check GPIO, resistor, polarity, and board model. A state report is not a light measurement.
For the group example (esp32-group-led), check each board's OUTPUT_INDEX. For missing initial state, check retention policy and actual connectivity. A board that reads other devices' info needs a larger receive buffer with setRxBuffer(): the server does not send a message larger than the default 80 bytes.
5. Duplicate UI updates or messages
- Compare first load with later navigation/reconnections. Increasing counts often indicate duplicate handlers or IO instances.
- Register handlers once, outside
ready; repeat subscriptions on ready. - Destroy exclusively owned IO instances on removal. For shared instances, remove only the component's handlers or call its
unlinkAll(component). - Direct messages fire both general
@and exact@topic. Avoid running the same work in both, and remove old manual event forwarding. - Repeat the action and confirm one intended UI update per message.
See lifecycle and compatibility.
6. Two connections with the same credentials
- Check the server's
duplicateLogin. With the defaultkeepNew(since 8.0.0) the later connection wins; an old JS client stops afterauth_clearand Arduino entersIO_STOP. WithkeepOldthe later connection receivesauth_fail. - Issue separate credentials for each device and app. Devices sharing one key disconnect each other.
- If a device cannot reconnect after a reboot on a
keepOldserver, check whether the previous connection is still open. It reconnects after the heartbeat removes it.
See duplicate logins for the policy.
Information for a reproducible report
Exclude passwords, device keys, and tokens.
Guide / example folder:
Failing step:
OS / browser / Node.js or board:
IOSignal and related library versions:
Example commit or download date:
Commands / server address and ports (no secrets):
Expected / actual result:
change and error output / reproduction steps:
Physical-device checklist
- Do the installed Arduino library/core versions, board, and wiring match the example?
- After compiling and uploading, does the board join Wi-Fi and print
READY CID:on serial? - Do the web app and board use the same server, and is the web app
ready? - For default, search, and group tags, are both in the same HOME CHANNEL environment?
- Do the received tag, type, and value match the guide?
- After sending a command, do the physical output and reported state agree?
- After reconnecting, did you resubscribe or select the new CID?
- After reconnecting or a power cycle, are retained state and initial outputs correct?
Compilation does not verify physical communication. Public-service authentication and hardware behavior require checks in the actual environment.