Esta página ayuda cuando un dispositivo no puede conectarse a Hermetry, es rechazado al iniciar sesión o sigue perdiendo su conexión. Cubre MQTT y la API HTTP del dispositivo. Para dispositivos LoRaWAN consulte Troubleshooting joins; para dispositivos de sondeo consulte Polling intervals, back-off and quota.
Where to look first
| Place | Shows |
|---|---|
| The device’s Log tab | Every login refusal with its reason, and every disconnect with its reason. The reason behind a refusal is never sent to the device: it is only here. |
| The device’s Connection details card | The broker host and ports your device must use |
| The client’s own log | The CONNACK code or HTTP status it received, or the TLS error |
Step 1: Can the device reach the broker?
| Symptom on the device | Cause | Fix |
|---|---|---|
| DNS lookup fails, or the connection times out | Wrong host, or a firewall blocks the outbound port | Use the host on the Connection details card, for your organisation’s region. Allow outbound TCP 8883 (and 443 for HTTPS). |
| The TLS handshake fails | The device connects by IP address (SNI is required), has no CA bundle, or its clock is far off so the certificate looks invalid | Connect by host name; use the system’s CA store; set the clock (NTP) |
| TLS fails on a very small device | It supports only old cipher suites or TLS 1.0/1.1 | TLS 1.2 is the minimum, with ECDHE and GCM or ChaCha20 suites. Update the TLS library. |
| Port 1883 is refused | The profile is TLS only (port 8883), the default | Use 8883, or, only on a private network, allow plain MQTT on the profile |
| A client certificate is rejected during the handshake | The certificate is not from Hermetry’s device CA, or it was revoked | An untrusted certificate ends the handshake; there is no fallback to a password. See Device certificates. |
See Device transport security.
Step 2: Is the login accepted?
MQTT answers the CONNECT with a CONNACK code:
| CONNACK | Meaning | Usual causes |
|---|---|---|
| 1 | Protocol version not supported | The client sends MQTT 5. Hermetry speaks MQTT 3.1.1. |
| 2 | Client ID rejected | The client ID is empty, longer than 64 characters or has characters outside A–Z a–z 0–9 . _ : - |
| 3 | Server unavailable | The service is starting or busy, or your address is briefly blocked after repeated failed logins. Back off and retry with jitter. |
| 4 | Bad username or password | The token or password is wrong, was rotated or revoked; a username without a password is read as an access token |
| 5 | Not authorised | See the table below. The exact reason is on the device’s Log tab. |
| Reason behind CONNACK 5 | Fix |
|---|---|
| The device is disabled | Enable it on the device page |
| The certificate is revoked or expired | Let the device renew, or recover it. See Device certificates. |
| The profile does not allow this login type | Allowed authentication on the profile’s Transport & auth tab |
| The device’s address is outside the profile’s Allowed networks | Add the network, or check which public address your site really uses (NAT, mobile carrier) |
| Plain MQTT on a TLS-only profile | Use port 8883 |
| The organisation is suspended | Ask an owner of the organisation. See Organisations and tenants. |
| The plan’s device or connected-device limit is reached | See Plans and the IoT add-on |
Over HTTP the same checks answer 401 (missing or unknown token), 403 (disabled, suspended, outside allowed networks, or a command poll over plain HTTP the profile does not allow: tls_required) or 404 (a token in the URL on a profile without Token in the URL). See Device HTTP API.
Login reminders
| Credential | Client ID | Username | Password |
|---|---|---|---|
| Access token | any valid ID | the token | empty |
| MQTT basic | any, or the pinned one | the username | the password |
| X.509 certificate | the device serial, equal to the certificate’s CN | ignored | empty |
A credential’s secret is shown once, when it is created or rotated. If it was lost, rotate it and update the device. See Device credentials.
Step 3: The device connects, then drops
The Log tab names the disconnect reason:
| Reason | Meaning | Fix |
|---|---|---|
keepalive_timeout | Nothing arrived within the keepalive time | Use a keepalive of 30 to 300 seconds and send PINGREQ; check the mobile link |
takeover | A second connection of the same device took over | Two devices share one credential, or a client reconnects without closing the old socket. Give every device its own credential. |
auth_revoked | The credential, the device or the organisation is no longer allowed | Sessions are re-checked about every 60 seconds; a rotated credential ends the old session |
rate_limit | The device kept breaking its rate limit (more than three times its minute allowance dropped within a minute) | Batch readings, send less often, or raise the profile’s limits |
inflight_exceeded | Too many unacknowledged QoS 1 messages (20 by default) | Wait for PUBACKs before sending more |
server_shutdown | A broker node restarted | Reconnect; nothing to fix |
uplink_window_expired | The Recent message online window ended | Expected for devices that connect only to send |
protocol_error, socket_error | The client broke the protocol, or the network failed | Update the client; check the link |
A device whose session is taken over again and again from two networks is held back for a while, and your administrators get a “takeover fight” notice.
Step 4: The device connects, but shows as offline
| Cause | Check |
|---|---|
| The profile’s online rule | Live connection, Recent message or Last seen only decide what “online” means. See Connection status and activity. |
| Quarantine | A self-registered device that waits in quarantine connects, but its data is acknowledged and dropped until an administrator activates it. See Quarantine. |
| The device is a gateway child | Its state comes from the gateway’s v1/gw/connect and v1/gw/disconnect messages. See Devices behind a gateway. |
One misconfigured device locks out others
Repeated failed logins from one address block that address for a short time, for every device behind it. Several devices behind one NAT or mobile router are then all refused with CONNACK 3 (HTTP 429). Find the device with wrong credentials (its Log tab shows the failures), fix it, and let the others retry with back-off.
Recommended device behaviour
- Connect over TLS by host name, with a keepalive between 30 and 300 seconds.
- After CONNACK 0, subscribe to the downlink topics, ask for shared attributes, report client attributes, then send buffered readings.
- On a refusal, back off: retry CONNACK 3 with jitter; wait at least 5 minutes after CONNACK 4; stop retrying CONNACK 1 and 2 until the configuration changes.
See MQTT.