Maintenance
Manage local state, caches, tracker data, playback state, captures, and recovery actions.
The tools on this page work on CrossWatch data stored locally. They do not directly change data in your connected provider accounts.
Maintenance overview
The Maintenance page is organized around individual tasks.
At the top of the page you can see:
Recommended actions, three safe tasks selected for your current usage
Needs attention, recent maintenance results that reported issues or failed
Last maintenance, the most recent task recorded in this browser
You can also use:
Run safe recommended, runs the current recommended safe tasks in sequence
View history, shows recent maintenance runs
Search, finds a maintenance task by name or description
Category, filters tasks by area
Risk level, filters Safe, Review first and Destructive actions
Task status, filters by Not run, Needs attention or Success
Risk levels
Each task has a risk label.
Safe
Read only, temporary cleanup, or an action designed to be safe during normal use
Review first
Changes local state or archives and should be understood before running
Destructive
Deletes or rebuilds local CrossWatch data and may remove history or cached state
Selecting a task or its information button shows the current local data affected by that action before you run it.
Depending on the task, this can include file size, database size, number of baselines, cached files, events, captures or last update time.
Recommended actions
CrossWatch shows three recommended safe tasks.
The initial recommendations are:
Retry provider items
Database health
Clear currently playing
Recommendations can adapt based on the safe maintenance tasks you use most often.
Run safe recommended executes the current three recommended tasks one after another. If a task fails or reports an unhealthy result, the sequence stops.
Sync
Rebuild sync state
Risk: Destructive
Removes the local provider baselines used by synchronization so the next sync starts from fresh provider data.
CrossWatch also clears pair scoped sync state associated with those baselines, including history aliases, mapping caches, watermarks and tombstones.
The next sync reads the provider data again and rebuilds the required translated aliases and baselines.
Use this when:
a release note specifically asks you to rebuild sync state
provider baselines are no longer trustworthy
a major provider or synchronization change requires a fresh baseline
This does not immediately change provider data, but it removes CrossWatch's remembered sync baseline. Review the next synchronization carefully, especially when removals are enabled.
Retry provider items
Risk: Safe
Clears temporary provider runtime data so previously deferred or failed items can be attempted again.
This includes temporary data such as:
retry guards
phantom records
provider health state
other temporary provider runtime files
CrossWatch preserves sync aliases, mappings, history indexes, watermarks, tombstones and custom anime mapping rules.
Use this when an item should be retried after fixing a provider, connection or matching problem.
Playback
Clear currently playing
Risk: Safe
Removes local live playback sessions from CrossWatch's Currently Playing state.
This is useful when a playback card remains visible after playback has already stopped.
Provider playback history is not changed.
Clear Recent Scrobbles
Risk: Destructive
Removes scrobble entries from CrossWatch Recent Activity.
Other Recent Activity entries remain available and provider watch history is not changed.
Use this only when you intentionally want to clear the locally recorded scrobble activity.
Reports & Metadata
Rebuild statistics
Risk: Destructive
Clears local Statistics, saved sync Reports and generated Insight caches.
These are rebuilt from future sync activity.
Use this when dashboard statistics or generated reports no longer reflect the state you expect.
Existing saved sync report data is removed. CrossWatch starts building new statistics and reports from subsequent activity.
Refresh artwork & metadata
Risk: Safe
Removes cached artwork and metadata.
CrossWatch downloads or regenerates the required data again when it is needed.
Use this when:
artwork is outdated
incorrect metadata is still shown after a matching change
cached metadata needs to be refreshed after an update
The cache is populated on demand, so it does not need to be rebuilt immediately.
Events
The Events tools manage the local event history archive used by CrossWatch.
Health check
Risk: Safe
Checks the event archive without modifying it.
The result includes information such as:
database integrity
event count
acknowledged events
archive size
archive availability
Use this first when Events or the sync activity calendar appear inconsistent.
Optimize archive
Risk: Safe
Compacts and reindexes the event archive to reclaim unused storage.
Events are retained.
This is useful when the archive has grown over time or after a large amount of event data has been removed.
Clear event data
Risk: Destructive
Deletes every event category and the sync activity calendar.
This includes sync events, scrobble events and audit events.
Other CrossWatch database data is left untouched.
This cannot be undone.
Rebuild archive
Risk: Destructive
Removes the current event archive and rebuilds it from the runtime state that is still available.
Historical events that exist only in the event database may be lost.
CrossWatch configuration and provider runtime state are not changed.
Use this only when the archive itself needs to be reconstructed.
Sync State
CrossWatch stores synchronization baselines in its local database. These tools inspect and maintain that data.
Database health
Risk: Safe
Performs a read only health check of the local CrossWatch database.
The check includes:
database integrity
schema version
database size
table counts
provider feature baselines
baseline items
orphan rows
expired temporary rows
last sync state update
An unhealthy result is shown as Issues found and is included under Needs attention.
Compact sync state
Risk: Review first
Creates an app state backup and rewrites the synchronization state database in compact form.
The task reports the storage size before and after the operation and how much space was reclaimed.
Use this when the sync state database has grown significantly and you want to compact its storage without intentionally removing configured baselines.
CrossWatch asks for confirmation before running this action.
Prune stale state
Risk: Review first
Creates an app state backup and removes provider or instance baselines that are no longer referenced by configured sync pairs or scrobbler routes.
Before running it, the task details can show stale providers, instances, baselines and items that are candidates for removal.
Use this after:
deleting sync pairs
removing provider profiles
replacing provider instances
removing old scrobbler routes
CrossWatch asks for confirmation before pruning.
Archive & Recovery
CW tracker archive
Risk: Review first
The CW tracker archive manages the local data used by CrossWatch Tracker.
Select the CrossWatch Tracker profile you want to manage first.
The archive panel provides separate controls for:
Tracker state files
All snapshots
You can then clear the selected data, download an archive or import an existing archive.
Download archive
Select Download archive to export the selected CrossWatch Tracker profile as crosswatch-tracker.zip.
This can be used as a backup before making significant changes to local tracker data.
Import archive
Select Import archive and choose a .zip or .json file.
The archive is imported into the currently selected CrossWatch Tracker profile.
After importing tracker state, CrossWatch refreshes its local state so the updated tracker data is reflected in the interface.
Clear selected
Select one or both of:
Tracker state files
All snapshots
Then select Clear selected.
Tracker state and tracker snapshots can therefore be cleaned independently.
Check the selected Tracker profile before downloading, importing or clearing archive data when you use multiple profiles.
Captures
Clear all captures
Risk: Destructive
Deletes all saved provider captures from local storage.
Automatic CrossWatch Tracker snapshots are stored separately and are not removed by this action.
CrossWatch asks for confirmation before deleting the captures.
Deleted captures cannot be recovered through CrossWatch.
Danger zone
Factory reset
Risk: Destructive
Returns CrossWatch to a clean local installation state.
Factory reset removes local runtime data including:
sync state
provider runtime cache
CrossWatch Tracker files
statistics and reports
metadata cache
event archive data
TLS material
The current config.json is moved to a timestamped backup before the reset.
Saved provider captures in /config/snapshots are kept.
Factory reset requires two confirmations, first the warning dialog, then entering RESET.
After the reset CrossWatch restarts.
Factory reset removes configuration from active use and deletes most local runtime state. Use it only when you intentionally want to return CrossWatch to a clean setup.
Task details
Select a maintenance task or its information button before running it to inspect the affected local data.
The detail panel is read only.
Examples of information shown include:
current database or file size
number of provider baselines
number of baseline items
stale state candidates
event archive statistics
number of cached files
capture count
last update time
If the status information cannot be loaded, the maintenance action remains available.
Maintenance history
Select View history to see the latest maintenance results.
CrossWatch stores up to 100 entries for the current account in the current browser.
The history records:
task
date and time
Success, Issues found or Failed
whether the task was part of a recommended batch
Needs attention
A maintenance action is marked as needing attention when its most recent result in the current browser is:
Issues found
Failed
Select the Needs attention card to filter the page to those tasks.
For health checks, an Issues found result normally means CrossWatch completed the check but detected a problem that should be reviewed.
Storage details
Expand Storage details at the bottom of the page to inspect the main maintenance storage locations.
The page shows:
CrossWatch Tracker state and snapshot counts
provider runtime cache file count
CrossWatch Tracker storage path
provider cache storage path
Typical locations are:
These details are mainly useful for troubleshooting or verifying that cleanup actions affected the expected local storage.
Which action should I use?
An unresolved item should be attempted again
Retry provider items
Currently Playing contains a stuck item
Clear currently playing
You suspect local database problems
Database health
Event history appears unhealthy
Health check
The event archive is large
Optimize archive
Artwork or metadata is outdated
Refresh artwork & metadata
Old provider or pair baselines remain after configuration changes
Prune stale state
Sync state storage needs compaction
Compact sync state
A release requires completely fresh synchronization baselines
Rebuild sync state
Statistics or Reports need to start fresh
Rebuild statistics
You want to back up CW Tracker data
CW tracker archive, Download archive
You want a completely clean CrossWatch setup
Factory reset
Recommended troubleshooting order
For most synchronization problems, start with the least invasive option.
Run Retry provider items.
Run Database health.
Check the Analyzer and Logs for the affected items.
If provider baselines are known to be invalid, run Rebuild sync state.
Review the next synchronization before applying changes.
Do not use Factory reset as a normal troubleshooting step.
Maintenance fixes local CrossWatch state. It does not fix incorrect credentials, provider outages, unsupported provider features or an incorrect sync topology.
Last updated
Was this helpful?