Skip to content

Troubleshooting

dkwolf1 edited this page Nov 11, 2026 · 2 revisions

Troubleshooting

Start by updating the integration, restarting Home Assistant, and confirming the Deco web interface is reachable from the same network as Home Assistant.

Quick error guide

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

Unexpected error during setup

An "Unexpected error" message is only the frontend summary. The useful reason is in Settings > System > Logs.

Check, in order:

  1. Use the main Deco's exact local web address, including the scheme.
  2. Use username admin and the owner password.
  3. Disable SSL verification for a self-signed certificate.
  4. Confirm the password works in a private browser window.
  5. Sign out the owner account from the mobile app and other browser sessions.
  6. 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.

Authentication and session conflicts

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.

Syslog receiver shows no messages

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.

Forwarding only the newest 1000 of ... Deco system log lines

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.

Deprecated CONN_CLASS_CLOUD_POLL warning

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.

One failed client refresh during a reload

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.

Timeouts and slow polling

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:

  1. Reboot all Deco nodes.
  2. Increase the regular polling interval.
  3. Increase Timeout seconds modestly.
  4. Keep retry count low to avoid long polling cycles.
  5. Increase the Deco status interval or set it to 0 when device_list affects wireless backhaul.
  6. 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.

Wrong or missing clients

  • 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.

Trackers become unavailable after one node fails

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.

Extra or combined devices

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.

Firmware update broke the integration

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.