Repository navigation
Troubleshooting
Start by updating the integration, restarting Home Assistant, and confirming the Deco web interface is reachable from the same network as Home Assistant.
| Symptom or log message | Most likely cause | What to do |
|---|---|---|
| Integration is not found | Incorrect manual directory or no restart | Verify custom_components/tplink_deco/manifest.json and restart Home Assistant |
Cannot connect to host |
Wrong IP, missing scheme, wrong protocol, routing, or firewall | Open the same full http:// or https:// address in a browser and use the main Deco address |
CERTIFICATE_VERIFY_FAILED |
Self-signed local HTTPS certificate | Disable Verify SSL certificate is valid |
invalid_auth, -5003, or login rejected |
Manager credentials, wrong owner password, copy/paste error, or lockout | Use username admin, the owner password, and sign out owner sessions |
| HTTP 401 or 403 after login | Stale or displaced owner session | Update the integration, close owner app/browser sessions, reload, and capture the retry sequence if it persists |
| Repeated timeouts | Slow or overloaded Deco firmware | Reboot the mesh, increase timeout cautiously, increase polling interval, and inspect diagnostics |
| Clients show zero or are missing | Client endpoint failure or incorrect Deco app data | Compare with the Deco app and local web UI; update firmware and integration |
| Extra devices are linked | Another integration exposes the same MAC address | Disable MAC linking in options or accept Home Assistant's combined device |
| Startup is slow | Old integration waiting for initial client refresh | Update to v3.14.2 or newer |
| Duplicate polling switch | Old multi-entry unique ID | Update to v3.15.0 or newer and restart; migration preserves the old entity ID |
An "Unexpected error" message is only the frontend summary. The useful reason is in Settings > System > Logs.
Check, in order:
- Use the main Deco's exact local web address, including the scheme.
- Use username
adminand the owner password. - Disable SSL verification for a self-signed certificate.
- Confirm the password works in a private browser window.
- Sign out the owner account from the mobile app and other browser sessions.
- Restart Home Assistant and reproduce once with debug logging.
If the log says unexpected character, expected a JSON value, the selected address may be returning an HTML page, redirect, proxy page, or other non-API response. Verify the final browser URL and protocol.
The Deco permits a limited number of local owner sessions. Logging into the app or web portal as the owner can invalidate Home Assistant's session. Use a manager account for daily app access and reserve the owner account for Home Assistant.
Current releases automatically recover from common stale-session 401/403 responses and apply bounded handling for transient HTTP 500 client endpoint failures. Persistent failures still require logs because firmware behavior differs.
See Syslog for the full test procedure. Check the saved host, port and protocol first: UDP and TCP listeners are separate, and a receiver on port 5514 will not receive data sent to the default port 514. The address must be reachable from Home Assistant, not just from the receiver itself.
The first successful download after enabling only records a starting position. Allow another interval and generate a normal router log event. The default interval is five minutes.
Check inbound firewall rules for the actual protocol, active network profile and HA source address. VPN software or guest-network isolation can block traffic. Do not turn off the whole firewall to test this.
A local test message confirms only the local receiver. A HA message saying it forwarded lines does not prove UDP delivery; confirm real messages from HA at the receiver.
This is an intentional limit, not a crash. If 3,322 new lines are fetched, only the newest 1,000 are sent and 2,322 are skipped. They are not queued for a later poll.
Use a more selective minimum log level when full detail is unnecessary. Do not automatically shorten the interval on a busy mesh: downloads occupy the shared router API session. For a one-off full log, use the manual download action and handle the result as sensitive data.
Update to stable v3.15.0 or newer and fully restart Home Assistant. The declaration was removed in #658 after beta.2 was published. Check the timestamp: an old warning can remain visible after updating. Similar warnings from other integrations are not fixed by updating TP-Link Deco.
An in-flight refresh can end with success: False while an options change unloads the entry. Check that setup and subsequent refreshes succeed. Persistent failures or tracebacks outside reload need investigation; do not dismiss them as expected cancellation.
A single isolated timeout followed by a successful retry is not necessarily a fault. Repeated failures require investigation.
Try these changes one at a time:
- Reboot all Deco nodes.
- Increase the regular polling interval.
- Increase Timeout seconds modestly.
- Keep retry count low to avoid long polling cycles.
- Increase the Deco status interval or set it to
0whendevice_listaffects wireless backhaul. - Compare the client list in the Deco app and local web interface.
Some X20 firmware has been reported to briefly interrupt wireless backhaul while processing device_list. Startup-only Deco status polling is the preferred mitigation; client and performance polling can continue.
- Confirm whether the Deco app itself shows the correct active client list.
- If both the app and Home Assistant are wrong, the problem is likely firmware-side.
- Update to the latest integration before comparing counts.
- Allow at least one full client polling cycle after startup.
- Download diagnostics and check
client_coordinator, query mode, timeouts, backoff, and last error.
An X50 V1.2 case on firmware 1.4.5 Build 20240828 Rel. 84587 returned an incorrect client list in both the app and Home Assistant. TP-Link beta firmware 1.8.5 Build 26082813 Rel. 27740 corrected the router-side issue. Availability of that firmware may vary by region.
Update first. Current releases handle per-node client failures independently, preserve known state for failed nodes, and use bounded global fallback behavior. If all trackers still become unavailable, provide diagnostics and logs showing the first failing node request.
Home Assistant combines devices from different integrations when they share identifiers such as a MAC address. This is expected. Disable Link client trackers to devices by MAC address to prevent future matching. Existing combined devices may need manual cleanup.
TP-Link changes local endpoints between firmware releases. Include the exact model, hardware revision, full firmware build, and whether the local web UI and Deco app still return correct data. Do not assume that behavior from another hardware revision applies to yours.
See Diagnostics-and-Bug-Reports before opening an issue.