Skip to main content

Troubleshooting

Start at the failing step and proceed only after the earlier step works.

SymptomStart here
Installation fails or the web page does not openInstallation
The page opens but never becomes readyConnection
Ready, but no messagesDelivery
Device missing or LED unchangedDevice control
Duplicate messages after navigation or reconnectionDuplicates
After another connection logs in with the same credentials, the old one drops and does not reconnectDuplicate logins

1. Installation and startup​

For the web chat examples in the iosignal-examples repository:

  1. Check node --version and npm --version. Use Node.js 22.16 or later and check the example's engines requirement.
  2. Open the example folder containing package.json and package-lock.json, not the repository root.
  3. 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.
  4. Run npm run dev. If you see EADDRINUSE, stop the process already using the port or update matching server/client settings.
  5. Open the web URL, http://localhost:5175 for 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​

  1. Ensure the IOSignal server is running. The quickstart requires a separate server; example dev starts one, while preview requires npm run server separately.
  2. Match the server URL: quickstart WebSocket port is 7777; Vanilla chat WebSocket port is 7779; its web page uses 5175.
  3. localhost means the machine running the client. Use the server's LAN address or domain from another device, and check its listening address and firewall.
  4. HTTPS pages need a trusted TLS-enabled WSS endpoint. Changing ws to wss alone does not configure TLS.
  5. 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​

  1. Connect sender and receiver to the same server. Framework examples use different ports.
  2. Match tags exactly, including case and #, @, $. The chat uses openchat; quickstart uses hello#message.
  3. Subscribe before sending to ordinary channels. From 9.6.0, listen() auto-subscriptions are sent before the ready event. With manual subscriptions, call subscribe() then signal() inside ready. Clients at 9.0.x or earlier send auto-subscriptions after ready handlers, so check the version.
  4. Send direct messages to the recipient CID and handle @ or @topic. Do not wait for direct messages in message or call subscribe('@topic').
  5. 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​

  1. 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://.
  2. Confirm the web client and board use the same server. WebSocket and TCP ports can differ.
  3. 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 to deviceCID@$name and deviceCID@$ui directly separates discovery from device-info problems. $name is name or name:category; $ui is a button list (ON,OFF) or a value starting with t=, p= or v=, such as t=light.1. The type must be listed at device types (such as light.1). See Build a device (app.iosignal.net compatible) for the rules.
  4. 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.
  5. 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​

  1. Compare first load with later navigation/reconnections. Increasing counts often indicate duplicate handlers or IO instances.
  2. Register handlers once, outside ready; repeat subscriptions on ready.
  3. Destroy exclusively owned IO instances on removal. For shared instances, remove only the component's handlers or call its unlinkAll(component).
  4. Direct messages fire both general @ and exact @topic. Avoid running the same work in both, and remove old manual event forwarding.
  5. Repeat the action and confirm one intended UI update per message.

See lifecycle and compatibility.

6. Two connections with the same credentials​

  1. Check the server's duplicateLogin. With the default keepNew (since 8.0.0) the later connection wins; an old JS client stops after auth_clear and Arduino enters IO_STOP. With keepOld the later connection receives auth_fail.
  2. Issue separate credentials for each device and app. Devices sharing one key disconnect each other.
  3. If a device cannot reconnect after a reboot on a keepOld server, 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​

  1. Do the installed Arduino library/core versions, board, and wiring match the example?
  2. After compiling and uploading, does the board join Wi-Fi and print READY CID: on serial?
  3. Do the web app and board use the same server, and is the web app ready?
  4. For default, search, and group tags, are both in the same HOME CHANNEL environment?
  5. Do the received tag, type, and value match the guide?
  6. After sending a command, do the physical output and reported state agree?
  7. After reconnecting, did you resubscribe or select the new CID?
  8. 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.