Maintenance

Manage local state, caches, tracker data, playback state, captures, and recovery actions.

Manage local CW state, caches, tracker data, playback state, reports, metadata, captures, and recovery actions.

Open Settings → Maintenance.

Maintenance tools operate on local CW data.

They do not directly remove watch history, ratings, watchlist entries, or playback data from connected provider accounts.

Create a backup before clearing tracker data, sync state, or performing a Factory reset.

Maintenance interface

The Maintenance window groups actions into these categories:

• Sync
• Local cleanup
• Playback
• Reports & Metadata
• Captures
• Danger zone

Select an action to inspect the current local data associated with it.

Depending on the action, CW can display:

• File counts
• Item counts
• Storage usage
• Last modified time
• Provider baseline counts
• Tracker state and snapshot counts
• Current storage paths

Each action reports whether it is running, completed, failed, or cancelled.

Completed actions can also report the number of removed files, removed items, and released storage.

Running maintenance actions

Each action has its own Run button.

You can also run all actions in a category by selecting Run beside the category name.

While an action or category is running:

• Other Maintenance actions are disabled
• The Maintenance window cannot be closed
• The current action displays its running state

Maintenance requests time out after 45 seconds.

Overview cleanup

The Overview Run button performs the standard local cleanup sequence.

It includes:

• Rebuild sync state
• Retry provider items
• Clear Recent Scrobbles
• Rebuild statistics
• Refresh artwork and metadata
• Clear currently playing

It does not include:

• Reset local tracker
• Clear all captures
• Factory reset

The Overview cleanup keeps provider connections, configuration, local tracker data, tracker snapshots, and saved captures.

Use the Overview cleanup when several areas of local CW state need to be refreshed together.

The next sync may take longer because provider baselines and local caches must be rebuilt.

Run the next sync as a Dry Run when the previous sync behavior was unexpected.

Sync tools

Rebuild sync state

Rebuild sync state removes the saved provider baselines used by sync pairs.

The next sync reads fresh data from the configured providers and creates new baselines.

Use it for:

• A sync plan that remains stuck
• Incorrect pair baselines
• Large changes made directly on a provider
• Switching sync direction or pair behavior
• Progress, History, Ratings, Watchlist, or Playlist state that needs to be relearned

This action removes the local sync state file.

It does not clear tracker data, provider accounts, playback activity, or saved captures.

Retry provider items

Retry provider items clears temporary provider runtime data.

This includes data associated with:

• Unresolved items
• Phantom items
• Tombstones
• Blackbox records
• Flapping protection
• Provider health
• Dropped item state

Use it when:

• Items remain unresolved
• Failed items are not retried
• Provider health remains stale
• Temporary provider errors have already been resolved
• Tombstone or retry behavior appears incorrect

Review the affected Events records first.

Events preserves the failure history before this action clears retry-related state.

The action preserves local activity and playback files, including:

• activity_history.json
• currently_watching.json
• auto_remove_seen.json
• watchlist_wl_autoremove.json

It also preserves the local identity cache directory.

Local cleanup

Reset local tracker

Reset local tracker clears CW tracker data for Watchlist, History, and Ratings.

Two options are available.

Tracker state files

Removes the current tracker JSON files.

All snapshots

Removes saved tracker snapshots from the tracker snapshot directory.

At least one option must be selected.

Tracker state and snapshots can be cleared independently.

This action does not change connected provider accounts.

Use it when:

• Local tracker results are incorrect
• Tracker data is corrupted
• CW must rebuild its local tracker from provider data
• Old tracker snapshots are no longer required

Resetting tracker state may cause the next tracker load or sync to take longer.

Playback tools

Clear currently playing

Clear currently playing removes the local live playback session file.

Use it when:

• Playback remains visible after it has stopped
• A stale session remains in Currently Playing
• The Playback Progress display does not refresh

Only the local CW playback state is removed.

Provider playback history and provider progress are not changed.

Clear Recent Scrobbles

Clear Recent Scrobbles removes scrobble entries from the local Recent Activity data.

Other activity entries remain available.

Use it when:

• Recent Scrobbles contains outdated entries
• Duplicate local scrobble events are displayed
• The Recent Scrobbles widget must be refreshed

This action does not remove provider watch history, provider progress, or scrobble data already sent to an external service.

Reports & Metadata

Rebuild statistics

Rebuild statistics clears locally generated statistics, reports, and Insights data.

The Maintenance interface currently removes:

• The statistics file
• Saved sync reports
• Generated Insights cache files

It does not remove the main provider sync state as part of the standard Maintenance action.

Statistics and Insights are rebuilt from future CW activity and sync runs.

Use it when:

• Dashboard totals are incorrect
• Reports contain outdated data
• Statistics remain stale after other cleanup actions
• Insights data no longer matches current local state

Historical reports that are removed cannot be reconstructed unless the underlying activity is processed again.

Refresh artwork and metadata

Refresh artwork and metadata removes locally cached artwork and metadata.

New copies are downloaded only when CW requires them.

Use it for:

• Incorrect posters
• Missing artwork
• Outdated metadata
• Corrupted cached images
• Excessive metadata cache storage

This action does not change media metadata stored by connected providers.

Captures

Clear all captures

Clear all captures deletes every saved provider capture from local storage.

Use it when:

• Old diagnostic captures are no longer required
• Capture storage must be cleared
• Provider capture data contains outdated information

This action requires confirmation.

The action cannot be undone.

Tracker snapshots and provider captures are separate data sets.

Clearing captures does not clear tracker snapshots.

Danger zone

Factory reset

Factory reset returns CW to a clean installation state.

It removes local generated data including:

• Sync state
• Provider runtime cache
• Local tracker data
• Statistics
• Sync reports
• Metadata cache
• TLS material
• Other generated CW runtime directories

Before removing configuration, CW moves config.json to a timestamped backup file.

Factory reset requires:

• A confirmation dialog
• Entering RESET

The following snapshot location is preserved:

/config/snapshots

Tracker snapshots stored inside the local tracker directory can be removed because the tracker directory itself is part of the reset.

After a successful reset, CW closes the Maintenance window and restarts the application.

Factory reset is destructive.

Use it only when normal Maintenance actions do not resolve the problem.

Maintenance status information

The Maintenance overview displays local tracker and provider cache information.

Tracker information

CW displays:

• Tracker root path
• Number of tracker state files
• Number of tracker snapshots

The default tracker path is:

/config/.cw_provider

The configured tracker root can differ when a custom CW tracker directory is configured.

Provider cache information

CW displays:

• Provider cache root path
• Number of provider runtime files

The default provider cache path is:

/config/.cw_state

Backup and Restore

Backup and Restore is managed separately from the Maintenance tools.

Use Backup and Restore to:

• Create backups
• Import backups
• Validate backups
• Restore backups
• Schedule backups
• Download backups
• Delete local backups

Create a backup before Factory reset or before removing tracker state that may be difficult to rebuild.

Related topic: Backup & Restore

Debug logging

Debug logging is configured separately from the Maintenance tools.

Available levels are:

off

Logs warnings and important messages.

on

Adds more information about sync runs and provider calls.

mods

Includes provider module debug output.

full

Provides the highest available log detail for troubleshooting.

Changing the debug level does not change sync results.

Higher logging levels can generate substantially more output and should normally be enabled only while investigating a problem.

Main → Output → Debug can still control Output panel detail independently.

Related topic: Output panel

Restart CW

Restart is not an action inside the current Maintenance tools list.

CW can still be restarted through the available application restart control or the Maintenance API.

Restarting:

• Reloads configuration and application code
• Does not reset provider connections
• Does not remove local state
• Terminates the current CW process

Do not restart CW during an active sync unless the process is no longer responding.

A process supervisor or container runtime must start CW again after the process exits.

API reference

Read status

Maintenance action status

GET /api/maintenance/action-status/{action}

Supported action values include:

• state
• cache
• tracker
• playing
• scrobbles
• stats
• metadata
• captures
• defaults

The response contains action-specific metrics and explanatory text.

Provider cache status

GET /api/maintenance/provider-cache

Returns the provider cache root, file information, and file count.

Tracker status

GET /api/maintenance/crosswatch-tracker

Returns the tracker root, tracker files, snapshot files, and counts.

Action endpoints

Rebuild sync state

POST /api/maintenance/clear-state

Retry provider items

POST /api/maintenance/clear-cache

Refresh artwork and metadata

POST /api/maintenance/clear-metadata-cache

Reset local tracker

POST /api/maintenance/crosswatch-tracker/clear

Request body:

{
  "clear_state": true,
  "clear_snapshots": false
}

At least one option should be true.

Clear Recent Scrobbles

POST /api/maintenance/clear-recent-scrobbles

Rebuild statistics

POST /api/maintenance/reset-stats

The Maintenance window sends:

{
  "recalc": false,
  "purge_file": true,
  "purge_state": false,
  "purge_reports": true,
  "purge_insights": true
}

This resets statistics, reports, and Insights data without removing the main provider sync state.

Clear currently playing

POST /api/maintenance/reset-currently-watching

Clear all captures

POST /api/snapshots/clear

Factory reset

POST /api/maintenance/reset-all-default

The Maintenance window sends an empty JSON object and handles the restart separately after a successful reset.

{}

Restart CW

POST /api/maintenance/restart

The endpoint schedules a hard process exit after approximately 0.75 seconds.

The service supervisor or container runtime must restart the process.

Compatibility endpoints

The following endpoints still exist but are not individual actions in the current Maintenance modal.

Clear provider sync cache

POST /api/maintenance/clear-provider-sync-cache

This combines:

• Rebuild sync state
• Retry provider items

It is retained for direct API use and compatibility.

Clear all activity

POST /api/maintenance/clear-activity-log

This removes the complete local activity log.

The current Maintenance modal exposes Clear Recent Scrobbles instead, which removes only scrobble rows.

Response format

Most destructive Maintenance endpoints return JSON containing:

• ok
• removed data
• before state
• after state
• summary

The summary can contain:

{
  "removed_files": 0,
  "removed_items": 0,
  "freed_bytes": 0
}

Failures normally return:

{
  "ok": false,
  "error": "error_description"
}

Troubleshooting

Sync results remain incorrect

Run these actions in order:

1. Rebuild sync state
2. Retry provider items
3. Run the affected pair as a Dry Run

Reset local tracker only when the issue concerns local tracker data.

Items remain unresolved

Run Retry provider items.

This clears temporary retry guards and provider health state.

Dashboard totals remain incorrect

Run Rebuild statistics.

New data is generated from future sync and activity processing.

Playback remains visible

Run Clear currently playing.

Scrobble rows remain visible

Run Clear Recent Scrobbles and reload the dashboard.

Artwork remains outdated

Run Refresh artwork and metadata.

The updated artwork appears after CW requests it again.

A category run stops before completion

A failed or cancelled action stops the remaining category sequence.

Review the action status and application logs before running the category again.

An action times out

The Maintenance interface stops waiting after 45 seconds.

Check the Output panel and application logs to determine whether the server action completed or failed.

Related topics

• Main dashboard
• Output panel
• Events
• Backup & Restore
• Recent Activity
• Insights
• Captures