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

1. Installation and startup​

For the web example bundle:

  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 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. listen() auto-subscription runs after ready handlers. For immediate sending inside ready, call subscribe() then signal().
  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 for READY CID: in the ESP32 serial monitor. 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 #notify plus a CID or #detect/ch plus a group. Confirm HOME CHANNEL scope and that the sketch responds to discovery tags. Entering the serial CID directly can separate discovery from control problems.
  4. Use the device CID, not the web client's CID. Anonymous clients can receive a new CID after reconnecting.
  5. Compare reported state and actual LED output. Check GPIO, resistor, polarity, and board model. A state report is not a light measurement.

For group control, check each board's OUTPUT_INDEX. For RGB, check the exact board, WS2812 pin, and expected four-byte BINARY payload. For missing initial state, check retention policy and actual connectivity. See board examples.

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. In 7.2.0, 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.

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:

Compilation does not verify physical communication. Public-service authentication and hardware behavior require checks in the actual environment.