Upgrade and Version Migration Troubleshooting

Use this page when an in-app update, a container image update, or a cross-version restore fails. Start with Updating ChannelWatch for the supported path; use Migrating from v0.7 only for those older installations.

Before you upgrade

Before either update path:

1. Create a manual backup from Settings > Backup.
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.

Update CenterCheck the installed app, image/runtime compatibility, and last update result before retrying. Download a private backup from the Backup tab first. Captured from ChannelWatch v1.6.0 with safe demo data.View full-size screenshot

Update Center failure states

Starting in v1.1.3, compatible app-only updates can run from Settings > Updates. The page may show one of these states:

State	What it means	What to do
image_required	The installed launcher or image cannot satisfy this release’s declared runtime or schema requirements.	Follow the image update guidance shown for that release. Compatible newer launchers can update some Python packages in-app; image-owned Python and system libraries still require an image update.
failed	Download, signature verification, archive validation, restart, or activation failed.	Read the job message, keep the pre-update backup, and retry only after the cause is clear.
rollback_available	ChannelWatch has previous runtime metadata.	Use Roll back if the new app bundle is unhealthy.

The in-app updater does not replace the Docker image. v1.6.5 has a direct in-app path from v1.5.3, v1.4.5, v1.4.1, and v1.4.0; do not assume every older image has that same path. On v1.4.x images, that release keeps the existing Python packages. See the version-specific update table before changing the container.

If a v1.4.x update says the restart could not be started, wait for rollback to finish. In Settings > Updates, confirm the previous version is running and the update controls are available. Review the offered version, then choose Retry now once. If it fails again, save the failed job message and container logs and ask for help.

Failed activation rollback

The container always starts an image-stable launcher first. If a newly activated app bundle fails during startup, the launcher rolls back to the previous runtime or the image copy and records the failure under /config/channelwatch-runtime/update-job.json.

If the UI is reachable, use Settings > Updates to review the last job. If the UI is not reachable, continue with Disaster Recovery.

Schema version mismatch errors

What the error means

This error appears when the backup’s settings schema is newer than the running app supports. Release numbers alone do not decide this: two releases can use the same settings schema.

Backups with an older supported schema can migrate forward. A backup with an ahead-of-installation schema must wait for a compatible app.

How to resolve it

1. Confirm which version created the backup.
2. Upgrade ChannelWatch to at least that version.
3. Retry after the running application supports that schema, whether it arrived through a compatible in-app update or an image update.

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

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

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 the current v1.6.5 image, the primary guide remains Migrating from v0.7. Use this page only when that normal path fails.

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

v6 to v7 session state archival

During migration from v0.7 to the current release, 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

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

CHANNELS_DVR_HOST and CHANNELS_DVR_PORT

CHANNELS_DVR_HOST and CHANNELS_DVR_PORT are deprecated compatibility variables for older single-DVR installs. v1.6.5 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

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

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

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. When ready to send a real sample notification, test one destination and confirm receipt. Follow the Diagnostics guidance; the unknown-test-name limitation on v1.6.0 was corrected in version 1.6.2.
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.

Related pages

• Migrating from v0.7 - the main upgrade procedure and rollback details
• Updating ChannelWatch - Update Center behavior and image-required releases
• Backup & Restore - restore behavior and schema compatibility rules
• Disaster Recovery - next steps when migration recovery fails completely
• Common Issues - reconnect flood behavior and other post-upgrade symptoms