> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/maintenance.md). # Maintenance Manage local CW state, caches, tracker data, playback state, reports, metadata, captures, and recovery actions. Open **Settings → Maintenance**. {% hint style="info" %} Maintenance tools operate on local CW data. They do not directly remove watch history, ratings, watchlist entries, or playback data from connected provider accounts. {% endhint %} {% hint style="warning" %} Create a backup before clearing tracker data, sync state, or performing a Factory reset. {% endhint %} ### 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](/crosswatch/main-dashboard/tools/events.md) 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](/crosswatch/settings/maintenance/backup-and-restore.md) ### 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](/crosswatch/main-dashboard/output-panel.md) ### 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: ```json { "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: ```json { "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. ```json {} ``` **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: ```json { "removed_files": 0, "removed_items": 0, "freed_bytes": 0 } ``` Failures normally return: ```json { "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](/crosswatch/main-dashboard.md) * [Output panel](/crosswatch/main-dashboard/output-panel.md) * [Events](/crosswatch/main-dashboard/tools/events.md) * [Backup & Restore](/crosswatch/settings/maintenance/backup-and-restore.md) * [Recent Activity](/crosswatch/settings/scrobbler/recent-activity.md) * [Insights](/crosswatch/main-dashboard/insights.md) * [Captures](/crosswatch/main-dashboard/navigation/captures.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.crosswatch.app/crosswatch/settings/maintenance.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.