Step 6 of 6

Troubleshooting

Device not connecting? Something not working? Here are the most common issues and exactly how to fix them.

Quick Diagnostic Steps
Follow these steps to identify the issue
1

Check Server Status

Ensure the IoT Control Hub server is running and accessible.

  • Open the dashboard in a browser
  • Check WebSocket connection indicator in sidebar
  • Verify server logs show no errors
2

Test Network Connectivity

Verify the device can reach the server.

  • From device: ping server IP address
  • Check firewall rules allow port 3000
  • Verify no VPN or proxy interference
3

Verify Device Registration

Confirm device exists in the system.

  • Check Devices page for your device
  • Verify token matches exactly
  • For biometric: verify serial number
4

Check Device Logs

Review device-side logs for errors.

  • Add console.log/print statements
  • Check WebSocket connection events
  • Verify message send/receive
5

Monitor Event Stream

Use the dashboard to see real-time events.

  • Open Event Stream page
  • Watch for device_connected events
  • Check for error events

Common Issues

Device shows as 'Offline'

Symptoms

  • Device appears offline in dashboard
  • No telemetry data received
  • Commands show as 'failed'

Possible Causes

  • Device not connected to network
  • WebSocket URL incorrect
  • Firewall blocking connection
  • Device token mismatch

Solutions

  1. 1Verify device has network connectivity (can ping server)
  2. 2Check WebSocket URL matches server address exactly
  3. 3Ensure port 3000 is accessible from device network
  4. 4Verify token in device code matches dashboard token
  5. 5Check server logs for connection attempts
  6. 6Restart the device and monitor connection
Authentication Failed

Symptoms

  • Device connects but disconnects immediately
  • 'Not authenticated' error in logs
  • No 'registered' confirmation received

Possible Causes

  • Incorrect device_id or token
  • Device not added to dashboard first
  • Token contains typos or extra whitespace

Solutions

  1. 1Copy device_id and token directly from dashboard
  2. 2Ensure device is registered before connecting
  3. 3Check for whitespace in token strings
  4. 4Verify JSON message format is correct
  5. 5For biometric: check serial_number matches device
No Telemetry Data

Symptoms

  • Device shows online but no data
  • Charts are empty
  • Telemetry page shows no records

Possible Causes

  • Device not sending telemetry messages
  • Incorrect message format
  • Telemetry interval too long

Solutions

  1. 1Verify device code sends 'telemetry' type messages
  2. 2Check payload is valid JSON
  3. 3Reduce telemetry interval for testing (e.g., 5 seconds)
  4. 4Add logging to device code to confirm sends
  5. 5Check server logs for received messages
Commands Not Received

Symptoms

  • Send command from dashboard
  • Device doesn't respond
  • Command shows 'delivered' but no action

Possible Causes

  • Device not handling 'command' message type
  • Command handler has error
  • Wrong command name expected

Solutions

  1. 1Add logging to command handler on device
  2. 2Verify device listens for 'command' type messages
  3. 3Check command name matches exactly (case-sensitive)
  4. 4Test with a simple 'ping' command first
  5. 5Verify payload parsing doesn't throw errors
Connection Keeps Dropping

Symptoms

  • Device reconnects frequently
  • Status flickers between online/offline
  • Gaps in telemetry data

Possible Causes

  • Unstable network connection
  • No heartbeat/ping implementation
  • Server timeout settings
  • Memory issues on device

Solutions

  1. 1Implement ping/pong heartbeat (every 30-60 seconds)
  2. 2Check WiFi signal strength on device
  3. 3Add reconnection logic with exponential backoff
  4. 4Monitor device memory usage
  5. 5Check for firmware updates
Biometric: No Attendance Data

Symptoms

  • Device online but no punch records
  • Attendance page empty
  • TimeLog_v2 not received

Possible Causes

  • XML format incorrect
  • Push/Cloud not enabled on device
  • Device not configured for real-time push

Solutions

  1. 1Verify Cloud Push is enabled in device settings
  2. 2Check device is set to real-time mode (not batch)
  3. 3Verify XML Operation matches 'TimeLog_v2'
  4. 4Test with a manual punch on the device
  5. 5Check device admin logs for push errors
Enable Debug Logging
Add these logs to your device code to diagnose issues
Debug Example (Node.js)
const DEBUG = true

function log(...args) {
  if (DEBUG) console.log("[IoT]", new Date().toISOString(), ...args)
}

ws.on("open", () => {
  log("Connected to server")
  log("Sending registration...")
})

ws.on("message", (data) => {
  log("Received:", data.toString())
})

ws.on("error", (err) => {
  log("ERROR:", err.message)
})

ws.on("close", (code, reason) => {
  log("Disconnected:", code, reason.toString())
})

Still Need Help?

If you're still experiencing issues after trying these solutions:

Send CommandsGo to Devices