Skip to content

Diagnostics and Bug Reports

dkwolf1 edited this page Nov 11, 2026 · 2 revisions

Diagnostics and Bug Reports

Good diagnostics distinguish an integration defect from a network, credential, session, or router-firmware problem.

Download Home Assistant diagnostics

  1. Open Settings > Devices & services.
  2. Open TP-Link Deco.
  3. Open the integration entry or a Deco device.
  4. Select Download diagnostics.

The diagnostics implementation redacts known sensitive configuration values including host, username, password, tokens, cookies, sessions, and stok. Deco and client identifiers are replaced with generated identifiers such as deco_1 and client_1.

The configured syslog receiver host is also redacted. This does not sanitize messages already sent to that receiver.

Diagnostics include:

  • integration configuration without credentials;
  • coordinator success, timing, timeout, and failure information;
  • query mode and HTTP 500 backoff state;
  • anonymized Deco model, hardware, firmware, topology, and performance data;
  • anonymized client state and assignment;
  • wireless and mobile endpoint availability.

Always review the downloaded file before posting it.

Enable debug logging

For a temporary test, open Settings > Devices & services > TP-Link Deco, use the integration menu to enable debug logging, reproduce the issue and then disable it. Home Assistant offers the collected log for download. Avoid leaving debug logging enabled indefinitely.

If temporary UI logging is unavailable, use the YAML alternative below. Merge it into any existing logger: section instead of adding a duplicate key.

Add this to configuration.yaml:

logger:
  logs:
    custom_components.tplink_deco: debug

Restart Home Assistant, reproduce the problem once, then open Settings > System > Logs and download the full log.

Remove or replace:

  • passwords and email addresses;
  • cookies, tokens, stok, and session identifiers;
  • encryption keys and complete encrypted payloads;
  • public IP addresses;
  • complete HTTP headers;
  • anything else that identifies your household or network unnecessarily.

Deco system log versus Home Assistant log

These are different files:

  • Home Assistant log: integration messages, tracebacks, retries, and coordinator behavior.
  • Home Assistant diagnostics: structured, automatically redacted integration state.
  • Deco system log: router-generated log downloaded by tplink_deco.download_system_log.

The Deco system log is not automatically redacted. Treat it as sensitive and inspect it before sharing.

Forwarded syslog messages are also raw router log content. They may contain authentication proofs, encrypted login material and certificate-related protocol output as well as client names and addresses. A screenshot of a receiver can expose the same information as a downloaded file.

HA debug logging and the syslog minimum log level are independent settings. Enabling debug logging helps inspect forwarding and polling but does not make raw Deco logs safe to share.

Reporting a syslog problem

Include the selected UDP/TCP protocol, receiver type, forwarding interval, minimum log level, whether the receiver actually received messages and whether normal polling continued. State whether the test was before or after an HA restart or integration reload.

Do not post an unredacted receiver screenshot or the entire router log. Start with the HA forwarding/error messages, diagnostics and a sanitized example only if necessary.

Information required for a bug report

Include all of the following:

  • TP-Link Deco integration version;
  • Home Assistant Core version and installation type;
  • Deco model and hardware revision;
  • complete firmware build;
  • router or access point operating mode;
  • host protocol (http or https), without exposing unnecessary address details;
  • whether SSL verification is enabled;
  • whether the owner account is active in the app or a browser;
  • exact reproduction steps;
  • expected and actual behavior;
  • diagnostics file;
  • sanitized log covering the first failure and any retry.

For client problems, also report whether the Deco app and local web UI show the correct clients.

Browser API captures

Only provide browser developer-tool request or response data when a maintainer explicitly requests it. Disable the integration first so it does not repeatedly replace the browser session.

Never publish raw encrypted login material, cookies, keys, tokens, or complete request headers. Decode and sanitize only the specific payload requested by the maintainer.

What is not enough

The following usually cannot be investigated alone:

  • "It does not work" without a traceback;
  • a screenshot containing only "Unexpected error";
  • an AI-generated diagnosis without reproduced evidence;
  • logs from a different integration;
  • a client count without comparison to the Deco app or local web UI;
  • a firmware version without the model and hardware revision.

Clone this wiki locally