doctor CLI

channelwatch doctor is a diagnostic CLI built into the container. It checks the things most likely to cause problems and tells you what to fix. Run it before opening a bug report.

Running doctor

All doctor subcommands run inside the container via docker exec:

docker exec channelwatch channelwatch doctor diagnose

The container must be running. If the container won’t start at all, check Common Issues first.

Subcommands

diagnose

docker exec channelwatch channelwatch doctor diagnose

The main diagnostic sweep. It checks every configured DVR server and reports:

DVR connectivity - can ChannelWatch reach the DVR’s HTTP API?
DVR authentication - is the API key valid?
DVR version compatibility - is the DVR version within the tested range?
Encryption key permissions - is /config/encryption.key readable only by the process owner (0600)?
Database integrity - does channelwatch.db pass SQLite’s integrity check?
mDNS reachability - if mDNS discovery is enabled, can the container see the local network’s multicast traffic?

For each check, diagnose prints a pass/fail result and a remediation hint when something fails.

Example output:

ChannelWatch Doctor v1.0
========================

DVR: Living Room (192.168.1.100:8089)
  Connectivity ......... OK
  Authentication ....... OK
  Version compat ....... OK (2025.06.15)

Encryption key
  Permissions .......... OK (0600)
  Readable ............. OK

Database
  Integrity ............ OK
  Schema version ....... 7

mDNS
  Multicast reachable .. OK

All checks passed.

A failing check looks like:

DVR: Living Room (192.168.1.100:8089)
  Connectivity ......... FAIL
  Hint: Connection refused. Verify the DVR host and port in Settings > DVR Servers.
        If using bridge networking, the host must be the LAN IP, not localhost.

config-check

docker exec channelwatch channelwatch doctor config-check

Validates settings.json against the current schema without starting the full application. Useful after manually editing the config file or after a failed restore.

If the config is valid, it prints a summary of what’s configured. If it’s invalid, it prints the specific field that failed validation and what value it expected.

debug bundle

docker exec channelwatch channelwatch doctor debug bundle

Produces a zip file at /config/channelwatch-debug-{timestamp}.zip containing:

Sanitized settings.json (API keys and passwords replaced with [REDACTED])
Recent log output (last 500 lines)
Database schema version and row counts (no alert content)
System info: Python version, OS, container uptime, memory usage
DVR connectivity results (same as diagnose)

The bundle is designed for sharing in a GitHub issue or Discussions thread. Review it before sharing to confirm the sanitization meets your comfort level.

rotate-encryption-key

docker exec channelwatch channelwatch doctor rotate-encryption-key

Generates a new encryption key, re-encrypts all stored DVR API keys with the new key, and replaces /config/encryption.key. The old key is not retained.

Run this if you suspect the encryption key has been compromised, or as part of a periodic security rotation.

Reading the output

Each check in diagnose output uses one of three statuses:

Status	Meaning
`OK`	Check passed. No action needed.
`WARN`	Something is unusual but not blocking. Review the hint.
`FAIL`	Check failed. The hint explains what to fix.

A WARN on DVR version compatibility means your DVR version is outside the tested range. ChannelWatch will still run, but behavior on untested versions is not guaranteed.

Common failure hints

“Connection refused” - The DVR host or port is wrong, or the DVR server is not running. If you’re using bridge networking, the host must be the LAN IP of the machine running Channels DVR, not localhost or 127.0.0.1.

“Authentication failed” - The DVR API key stored in ChannelWatch is wrong or expired. Update it in Settings > DVR Servers.

“Encryption key permissions are too open” - The /config/encryption.key file is readable by users other than the process owner. Fix with:

chmod 600 /your/config/path/encryption.key

“Database integrity check failed” - The SQLite database may be corrupted. Take a backup of the current state, then try restoring from a known-good backup. See Backup & Restore.

“mDNS multicast unreachable” - The container cannot see multicast traffic. This is expected in bridge networking mode. Switch to host networking (network_mode: host) to enable mDNS discovery, or add DVR servers manually.

Common Issues - fixes for the most frequent problems
Diagnostics - web UI diagnostic tools
Backup & Restore - recover from a corrupted database
Privacy - what the debug bundle contains and where it goes