Common Issues

This page covers the three most common problems users run into with ChannelWatch and how to resolve each one without touching source code.

No notifications

Notifications are silent when any link in the chain breaks: the container, the DVR connection, the provider credentials, or the alert configuration. Work through these steps in order.

1. Check the container logs

docker logs channelwatch

Look for lines marked ERROR or WARNING. Common messages include connection refused (DVR unreachable), authentication errors (bad provider credentials), and startup failures. If the log is empty or the container is not running, see Container won’t start below.

2. Verify DVR connectivity

Open the ChannelWatch web UI at http://your-server-ip:8501 and go to the Diagnostics tab. Run Connection Tests. A green result means ChannelWatch can reach your Channels DVR server. A red result means the host or port is wrong, or a firewall is blocking the connection.

If you’re using bridge networking instead of host networking, confirm that the DVR host is reachable from inside the container. The DVR address must be the host machine’s LAN IP, not localhost or 127.0.0.1.

3. Check provider credentials

Go to Settings > Notification Providers and confirm your credentials are entered correctly. Pushover requires both a User Key and an API Token. Apprise-based providers (Discord, Telegram, Slack, etc.) require the correct URL format for each service.

From the Diagnostics tab, use Alert Tests to send a test notification. If the test fails, the error message in the UI or in docker logs channelwatch will identify whether the problem is a bad credential, a network error, or a provider outage.

4. Confirm alerts are enabled

Go to Settings > Alert Types and verify that the alert type you expect is toggled on. A provider can be configured correctly but produce no notifications if the corresponding alert type is disabled.

5. Check for a startup grace period (disk alerts only)

Disk space alerts have a startup grace period (default 10 seconds) during which no alerts fire, even if free space is already below a threshold. If you restarted the container and expected an immediate disk alert, wait for the grace period to pass and check again.

Notification flood on reconnect

Symptom: Many notifications arrive in a burst immediately after the container restarts or after the DVR server reconnects.

Cause: When the container restarts, ChannelWatch re-establishes the event stream connection with your Channels DVR. If multiple viewers are active at the time, each active session triggers a fresh notification as ChannelWatch re-discovers them.

Fix: This behavior is addressed in v0.8 and later through persisted session state. After upgrading, session context survives container restarts so active viewers do not re-trigger notifications on reconnect.

If you’re on v0.7 and cannot upgrade yet, the workaround is to restart the container during off-hours when no one is actively watching.

Container won’t start

If docker compose up -d completes but the container exits immediately, or if the web UI is unreachable, check the following.

Port conflict

ChannelWatch uses port 8501 for the web UI. If another process on the host is already using that port, the container will fail to bind and exit.

Check what’s using the port:

ss -tlnp | grep 8501

If something else is using 8501, either stop that process or change ChannelWatch’s port. With bridge networking, map a different host port:

ports:
  - "8502:8501"

With host networking, there is no port mapping option. You would need to stop the conflicting process or switch to bridge mode.

Volume permission error

ChannelWatch writes configuration and logs to the /config volume. If the host directory is owned by root and the container process cannot write to it, the container will exit with a permission error.

Check the logs:

docker logs channelwatch

If you see Permission denied errors referencing /config, fix the ownership on the host:

sudo chown -R 1000:1000 /your/local/path

Replace /your/local/path with the path you mapped to /config in your compose file. The UID 1000 is the default non-root user inside the container.

Missing or malformed compose file

If the compose file has a syntax error, Docker will refuse to start the container. Validate it:

docker compose config

This prints the resolved configuration. Any YAML syntax errors appear as parse failures before the output.

Disk space alerts spamming

Symptom: You’re receiving repeated disk space alerts even though your free space hasn’t changed significantly.

ChannelWatch has built-in cooldown and worsening logic to prevent alert fatigue. If alerts are still repeating, one of these settings may need adjustment.

How the cooldown works

Once a warning or critical alert fires, ChannelWatch will not send another alert at the same severity unless both conditions are met:

Free space has dropped by at least 1 GB or 1 percentage point since the last alert at that severity.
The cooldown period has elapsed (default: 1 hour).

If you’re seeing repeated alerts, the cooldown may be set too low, or free space may be fluctuating enough to cross the worsening threshold repeatedly.

Adjusting the settings

Go to Settings > Disk Space Monitoring > Advanced to adjust:

Cooldown period — increase this to reduce how often repeat alerts fire at the same severity.
Worsening sensitivity — increase the minimum GB or percent drop required before a repeat alert fires.
Warning and critical thresholds — if your disk usage naturally hovers near a threshold, raise the threshold so normal fluctuation doesn’t keep crossing it.

Startup alert on every restart

If you receive a disk alert every time the container restarts, the startup grace period may be too short. Increase it in Settings > Disk Space Monitoring > Advanced under Startup grace period.

The grace period delays the first disk check after startup. Raising it to 30 or 60 seconds gives the container time to fully initialize before evaluating disk space.

Diagnostics — use the web UI diagnostic tools to test connectivity and alert delivery
CLI Commands — command-line alternatives for headless troubleshooting
Disk Space — full reference for disk alert thresholds and cooldown logic