Skip to content
ChannelWatch

Upgrade and Version Migration Troubleshooting

This page is for upgrade problems after you pull a new ChannelWatch image or restore data across versions. It extends the main Migrating from v0.7 guide by focusing on recovery steps when the upgrade does not go cleanly.

Before you upgrade

Section titled “Before you upgrade”

Take these steps before pulling the new image:

  1. Create a manual backup from Settings > Backup & Restore.
  2. Note the version you are currently running in the web UI.
  3. Read the Release Notes for the version you plan to install.

These steps matter because schema compatibility and rollback options depend on which version created the backup and which version is trying to read it.

Schema version mismatch errors

Section titled “Schema version mismatch errors”

What the error means

Section titled “What the error means”

This error appears when a backup was created by a newer ChannelWatch version than the one currently running. The older application does not know how to safely read a newer schema.

The same rule appears in Backup & Restore: backups from older versions can be migrated forward, but backups from newer versions cannot be restored into an older release.

How to resolve it

Section titled “How to resolve it”
  1. Confirm which version created the backup.
  2. Upgrade ChannelWatch to at least that version.
  3. Retry the restore after the container is running the newer image.

If the restore is blocked because the container itself cannot complete the upgrade, continue with Migration failed partway through.

Migration failed partway through

Section titled “Migration failed partway through”

ChannelWatch writes an automatic pre-migration backup before it changes schema-managed files. That backup is the safest recovery point when a version upgrade stops mid-process.

Recovering from a pre-migration backup

Section titled “Recovering from a pre-migration backup”
  1. Stop the container.
  2. Check /config/backups/ for the pre-migration backup written before the upgrade attempt.
  3. Restore that backup using the manual recovery path in Backup & Restore.
  4. Start the container again and review docker logs channelwatch during startup.

If you are migrating from v0.7 to v1.0, the primary guide remains Migrating from v0.7. Use this page only when that normal path fails.

Manual recovery if no backup exists

Section titled “Manual recovery if no backup exists”

If /config/backups/ is missing or no usable pre-migration backup exists, your recovery options are limited.

  • If the main problem is a damaged channelwatch.db file, try the database repair path in Disaster Recovery.
  • If no usable backup exists and repair fails, rebuild from scratch using the same disaster recovery page.

At that point the upgrade problem has become a broader recovery problem, not just a version mismatch.

Session state loss after upgrade

Section titled “Session state loss after upgrade”

v6 to v7 session state archival

Section titled “v6 to v7 session state archival”

During the v0.7 to v1.0 migration, ChannelWatch moves from the legacy default session state layout to per-DVR session state files. The migration can archive session_state_default.json and create per-DVR session files when the original state file is present.

That means session-related behavior after the upgrade depends on what existed in /config before the migration started.

If the default session file is gone

Section titled “If the default session file is gone”

If session_state_default.json was already missing before the migration ran, the new per-DVR session files start empty. That does not mean the upgrade failed. It means ChannelWatch has no prior session state to carry forward.

The visible symptom is often a burst of repeat notifications after the next restart or reconnect because active viewers are discovered again as new sessions. If that is what you see, compare it with Notification flood on reconnect.

Deprecated environment variable warnings

Section titled “Deprecated environment variable warnings”

CHANNELS_DVR_HOST and CHANNELS_DVR_PORT

Section titled “CHANNELS_DVR_HOST and CHANNELS_DVR_PORT”

CHANNELS_DVR_HOST and CHANNELS_DVR_PORT are deprecated compatibility variables during the v0.7 to v1.0 transition. The upgrade can still start with them present, but the container logs a warning so you know they should be removed.

The warning is not a migration failure by itself. It is a sign that you are still relying on the older single-DVR configuration style.

How to migrate to the new format

Section titled “How to migrate to the new format”

Follow the migration steps in Migrating from v0.7 and move to the supported configuration path there.

Do not remove the old variables until the upgraded container is running correctly and the DVR connection is confirmed in the web UI. Once the new configuration is working, remove the deprecated variables and restart the container.

Notification flood after upgrade

Section titled “Notification flood after upgrade”

This symptom usually has the same root cause as the reconnect flood documented in Common Issues: ChannelWatch re-establishes session state and sees currently active playback as new activity.

If you upgraded to a release that should preserve session state but still see a flood, check whether the session state migration completed as expected and review startup logs for migration warnings.

After a successful upgrade: verification

Section titled “After a successful upgrade: verification”

After the upgrade completes, verify the result before you treat the system as healthy:

  1. Open the web UI and confirm your DVR server settings are present.
  2. Go to Diagnostics and run Connection Tests.
  3. Check System Status for a healthy DVR connection.
  4. Send a test alert.
  5. Review docker logs channelwatch for any WARN or ERROR lines during the first minute after startup.

If these checks pass, the upgrade completed cleanly. If not, return to the migration guide and the recovery pages linked below.

Section titled “Related pages”