> 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 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. {% hint style="info" %} Most maintenance actions are only needed when troubleshooting, after significant configuration changes, or when a release note specifically recommends them. {% endhint %} ### 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. | Risk | Meaning | | ---------------- | -------------------------------------------------------------------------------- | | **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. {% hint style="info" %} Recommended actions never include tasks marked Review first or Destructive. {% endhint %} ### 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 {% hint style="warning" %} 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. {% endhint %} #### 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. {% hint style="warning" %} Existing saved sync report data is removed. CrossWatch starts building new statistics and reports from subsequent activity. {% endhint %} #### 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. {% hint style="danger" %} This cannot be undone. {% endhint %} #### 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. {% hint style="warning" %} Check the selected Tracker profile before downloading, importing or clearing archive data when you use multiple profiles. {% endhint %} ### 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. {% hint style="danger" %} Deleted captures cannot be recovered through CrossWatch. {% endhint %} ### 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. {% hint style="danger" %} 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. {% endhint %} ### 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 {% hint style="info" %} Maintenance history is browser local. It is not a server side audit log and does not follow you to another browser. {% endhint %} ### 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: ``` /config/.cw_provider /config/.cw_state ``` These details are mainly useful for troubleshooting or verifying that cleanup actions affected the expected local storage. ### Which action should I use? | Situation | Recommended action | | ----------------------------------------------------------------- | -------------------------------------------- | | 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. 1. Run **Retry provider items**. 2. Run **Database health**. 3. Check the Analyzer and Logs for the affected items. 4. If provider baselines are known to be invalid, run **Rebuild sync state**. 5. Review the next synchronization before applying changes. Do not use Factory reset as a normal troubleshooting step. {% hint style="warning" %} Maintenance fixes local CrossWatch state. It does not fix incorrect credentials, provider outages, unsupported provider features or an incorrect sync topology. {% endhint %} --- # 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.