Troubleshooting

Symptom-first fixes for the problems that actually happen — sorted by where you are in the pipeline: compile, connect, publish, see it on the dashboard.

Work top to bottom. Each section assumes the ones above it are healthy — there's no point debugging a graph while the Serial Monitor is printing connection failures.

It won't compile

Libraries aren't found (Arduino IDE) — the IDE only scans libraries/ at startup. If you copied the SDK folders in while the IDE was open, restart it.

credentials.h: No such file or directory — the code samples ship without credentials on purpose. Create the file next to your sketch and define your MQTT username and password, exactly as shown on the Settings page of the dashboard. See Connect — Arduino IDE.

Wrong board selected — an ESP32 sketch compiled for an ESP8266 (or a different ESP32 variant) fails with confusing, unrelated-looking errors. Confirm the board in Tools → Board before chasing anything else.

It won't connect

First, split the problem in two. WiFi and MQTT fail differently, and the Serial Monitor tells you which one you have.

Stuck before an IP address — it's WiFi, not us. Check SSID and password, and remember the ESP32 is 2.4 GHz only — it cannot see a 5 GHz-only network. Captive-portal networks (hotels, offices with a login page) won't work either.

WiFi connects, then failed to connect to mqtt, rc=… — now the code matters. The samples print the PubSubClient state code:

rc	Meaning	Usual cause
-2	Network connection failed	Wrong host or port, or a TLS handshake failure. Confirm `mqtt.ohioiot.com` and port `8883` with the CA cert loaded — see TLS & Security.
-4	Connection timeout	Something between you and the broker is eating the traffic — commonly a firewall blocking outbound 8883 on corporate or school networks. Try a phone hotspot to confirm.
4	Bad username or password	Credentials in `credentials.h` don't match the dashboard Settings page. Copy-paste them — don't retype.
5	Not authorized	The account exists but isn't allowed on — most often a lapsed subscription. Check Subscription Status on the Settings page.

Testing with a desktop tool like MQTT Explorer or mosquitto_sub is the fastest way to separate "my credentials are wrong" from "my device code is wrong." If the desktop tool connects with the same credentials, the problem is on the board.

It connects, then drops — over and over

Two devices, one identity. The broker allows one connection per client ID; when a second client connects with the same ID, the first is disconnected — and if both are set to reconnect, they take turns kicking each other off forever. This usually comes from cloning a board (or its flash) so two devices share a stored ID. See Device Identity for how IDs live in NVS and how to erase one so the device mints a fresh identity.

It drops exactly when it publishes. The broker refuses any single MQTT packet over ~100 KB and drops the connection. If your device dies every time it sends one particular message, measure that payload. Split the batch, or use the gateway publishing path for bulk data. Limits are listed in Broker Configuration.

It drops when nothing is happening. If your main loop blocks for longer than the keep-alive window (long delay() calls, slow sensor reads), the broker assumes the device is gone. Keep the client's loop() running; do slow work in smaller slices.

Connected, but nothing shows on the dashboard

This is almost always the topic, and the failure is silent by design: the broker quietly drops any publish outside your own namespace rather than disconnecting you. Check, in order:

First segment is your MQTT username — not your email, not the device name. A publish to anyone else's namespace goes nowhere, silently.
The type segment is one the platform routes — numb, bool, status, or config. A typo like num is just an unrouted topic. See Data Types & Routing.
You're looking at the right surface — numb and bool land on graphs; status and config update the device twin, not a chart.
The payload matches the type — numb expects a number. Publishing "23.5 C" to a numb topic isn't a number.

Fast way to see what's actually arriving: subscribe to your whole namespace from a desktop client (yourusername/#) and watch the raw traffic. If the message shows up there but not on the dashboard, the topic shape is the problem; if it doesn't show up at all, the publish is failing. See Subscribing.

Commands don't reach the device

Is the device subscribed? A command is a publish to a topic the device listens on — if the subscription isn't made (or was lost on reconnect and not re-established), the message sails past. Re-subscribe inside your on-connect handler, not just in setup().
Do the topics match exactly? Compare the Command's topic in the dashboard against the device's subscription character for character.
Feedback shows "sent" but never "received"? The platform published it; the device didn't answer. That points at the device-side handler. See Commands for the feedback lifecycle.

Rules exist, but no alert arrived

Did the rule actually fire? Check the in-app Messages screen first — it's the delivery channel with the fewest moving parts. If the message is there, the rule works and the problem is the outbound channel.
Cooldowns are working as intended. A value bouncing across a threshold doesn't send one text per bounce — see "Why your phone doesn't melt" in Rules & Alerts. If you got one alert and then silence, that may be the design, not a bug.
SMS specifically: the destination number must be entered with country code and have consented per the SMS alerts policy.

OTA update won't take

Device reverted to the old firmware. That's the safety net doing its job — a corrupted or non-booting image rolls back automatically. Verify the uploaded binary's hash matches your build, then re-release. See the security model in OTA Updates.
Update never starts. Confirm the device is in the group you released to, is currently online, and is running firmware with OTA support (the Champion tier — Minimalist and Scaler don't include it).
Update starts, then the device goes dark mid-flash. Power. Battery-powered devices at the edge of brown-out are the classic case — the rollback will recover it on next boot, but fix the supply before retrying.

Still stuck?

Grab the Serial Monitor output around the failure (the lines before it matter as much as the error itself), note which code sample and toolchain you're on, and contact us. A copy-pasted log beats a description of a log every time.

Next Step

Back to Docs

→