Troubleshooting

Start with the same alias you used in the failing command:

denki aliases
denki doctor "desk plug"

aliases shows saved names and the configuration path. doctor checks resolution, connectivity, device information, and supported capabilities. It also displays Wi-Fi RSSI and specific next steps for connectivity, authentication, and protocol failures. Weak signal is a warning; it does not fail an otherwise successful check. Its JSON output includes next_steps alongside warnings and error_code, and is useful for reporting a bug:

denki doctor "desk plug" --json

Review reports before sharing them. Remove local addresses, aliases, and anything private. Never include passwords or your credentials file.

Device not found or alias is ambiguous

Copy the full name from denki aliases. Exact normalized matches take precedence; a partial name must match only one alias. For Kasa, run denki scan to discover new devices. For Tapo, add the address explicitly with denki alias ... --klap.

Connection failed or timed out

Check that the device is powered and the computer can reach its local network. Guest Wi-Fi, client isolation, VPN routing, or a changed DHCP address may prevent access. Run denki scan for Kasa. For a moved Tapo device, use its current IP:

denki scan --tapo-target 192.0.2.50

Replace the placeholder IP. New targets negotiate TPAP/KLAP; saved targets use their configured protocol. For explicit KLAP mode, save a --klap alias first. Auto-mode identity reconciliation requires an existing --tapo alias. A failed old-address probe may still make scan exit nonzero even when a new-address probe succeeds. Inspect the individual results.

Tapo authentication failed

For P125 firmware advertising TPAP, re-save the alias with --tapo; --klap selects the original KLAP-only client. Use the account associated with the device. Save credentials again with denki login "you@example.com". If both TAPO_USER and TAPO_PASS are set, they override the saved credentials; check for stale values in your shell. Do not paste passwords into issue reports.

For auto-mode aliases, tpap_credentials means login was rejected and tpap_auth_attempts_limit means the device has locked logins. Stop retries, check the saved account credentials, and wait for lockout to clear. A state_mismatch or a power timeout leaves the state uncertain; read info before another write.

Unsupported operation or missing energy

Check the support table. Not every plug measures energy, and Tapo daily/monthly history differs from Kasa. A missing measurement is null in JSON or empty in CSV; it does not mean zero consumption.

Identity mismatch

The saved address now reports a different device identity, or none. Denki stops before sending control commands. First verify which physical device owns the address, for example in your router's device list. Do not delete the saved identity just to bypass the check. For Kasa, explicitly update a verified address with denki alias NAME IP; scan cannot authenticate a Kasa address change. For Tapo, scan can reconcile an authenticated identity (use --tapo-target IP for a new IP).

Kasa address change requires confirmation

identity_rebind_required means a discovery reply claims a saved Kasa device ID from a different IP. It may be a legitimate DHCP move or a forged LAN reply. Scan keeps the saved aliases unchanged. Verify the address independently, then update each affected alias with denki alias NAME IP. Repeating scan alone will not authorize the move.

Registry conflict or malformed configuration

registry_conflict means another process edited aliases during a scan. Run scan again after the other command finishes. Do not remove .lock sidecars.

For malformed hosts.json, back up the file shown by denki aliases before repairing its JSON. Denki preserves unreadable configuration instead of replacing it silently. See configuration paths.

Report a reproducible problem

Open an issue on GitHub with the device model, region, hardware/firmware version, Denki version (denki --version), exact command, error, and sanitized doctor output. Say whether the behavior happened on a real device or only in a simulator.

Unsafe local configuration

On Unix, Denki refuses configuration that another local user could replace or modify. Check ownership and permissions of the Denki configuration directory and its ancestors. Keep the Denki directory private (0700), credentials private (0600), and remove group/other write access from hosts.json and its ancestors. Do not recursively chmod your home directory or follow unexpected symbolic links. New Denki directories are created privately; unsafe existing ancestors are reported rather than silently modified. Root-managed system links are supported; user-owned linked configuration directories must be replaced with a real private directory at the configured location.

Set both non-empty TAPO_USER and TAPO_PASS, or unset both. A partial override now fails instead of silently using saved credentials. Credential parsing errors never include the malformed file contents.