Maintenance

Control log verbosity, run safe cleanup tasks, and restart the CrossWatch service.

Maintenance controls logging, cleanup, and service restarts. Open Settings → Maintenance.

Debug level

Use Debug to control log verbosity.

• off: warnings and important messages only.

• on: more detail about runs and provider calls.

• mods: on, plus provider-module debug.

• full: maximum detail. Use for troubleshooting. Logs get noisy.

You can change this anytime. It does not change provider data or sync results.

Maintenance tools

Open Maintenance Tools for one-click cleanup actions.

image

These actions are local to CrossWatch. They do not directly edit Plex/Trakt/SIMKL/Jellyfin/Emby. They can still delete local files. Back up if you are unsure.

These buttons are local-only cleanup/reset actions.

• They delete CrossWatch files on disk.

• The next UI load / sync run rebuilds state by reading providers again.

• The next sync may be slower and “noisier” because caches are gone.

Use these when:

• the UI shows stale info

• a cache got corrupted

• a sync keeps repeating the same actions

• stats/insights look wrong

• “currently playing” is stuck

The dialog shows:

• Tracker root: local tracker state and snapshots.

• Provider cache: provider cache and shadow files.

Storage locations (what CrossWatch deletes)

The UI shows the actual resolved paths from the API.

• Config directory: holds config.json and state.json (orchestrator baseline).

• Provider cache (.cw_state): provider “shadow” files, unresolved bookkeeping, currently_watching.json.

• Metadata cache (cache/): cached posters/artwork and metadata blobs.

• CrossWatch tracker (.cw_provider/ by default): watchlist.json, history.json, ratings.json, plus optional snapshots/*.json.

If paths shown in the UI differ from what you expect, trust the UI. It’s reading them from the backend.

Clear state

image

What it does

• Deletes /config/state.json.

• Forces a full rebuild on the next run.

Best for:

• bad or stuck sync plans

• relearning after big provider-side changes

Does not:

• remove items from Plex/Trakt/SIMKL/Jellyfin/Emby

• delete CrossWatch tracker snapshots

Advanced: API details

• Endpoint: POST /api/maintenance/clear-state

• Deletes: CONFIG_DIR/state.json

• Why you’d use it: force a clean baseline diff after a sync loop.

Clear provider cache

image

What it does

• Removes files in the provider cache directory (shown in the UI).

• Forces provider health and unresolved refetch.

Best for:

• provider health/unresolved counts that never change

• CrossWatch reusing obviously old provider data

Does not:

• change any provider libraries or history

Advanced: API details

• Endpoint: POST /api/maintenance/clear-cache

• Deletes: all top-level files under CW_STATE_DIR (not nested directories).

• The UI may list *.json, but cleanup removes any top-level file.

Remove metadata cache

image

What it does

• Deletes cached artwork and metadata under /config/cache.

• Forces a re-fetch when items are processed or viewed.

• Can free disk space.

Best for:

• wrong, corrupt, or outdated posters/artwork

• visual glitches caused by stale cached images

• large caches you want to prune

Does not:

• delete movies/shows or change provider libraries

• touch tracker state files or /config/.cw_state

Advanced: API details

• Endpoint: POST /api/maintenance/clear-metadata-cache

• Deletes: everything inside CACHE_DIR (files + directories).

Clear CrossWatch tracker

image

The CrossWatch tracker is a local backup of:

• Watchlist

• History

• Ratings

You will see two checkboxes:

• Tracker state files: removes current tracker state.

• All snapshots: removes tracker snapshots.

You can select one or both. If both are unchecked, nothing runs.

What it does

• Tracker state files: clears local tracker state files.

• All snapshots: deletes tracker snapshot backups.

Best for:

• forcing a clean tracker rebuild from live providers

• deleting old snapshots you no longer need

Does not:

• touch provider libraries or watch history

• modify /config/state.json (orchestrator state)

This deletes local container files. Typical names are watchlist.json, history.json, and ratings.json.

Advanced: API details

• Endpoint: POST /api/maintenance/crosswatch-tracker/clear

• Body:

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

• If clear_state=true: deletes TRACKER_ROOT/*.json

• If clear_snapshots=true: deletes TRACKER_ROOT/snapshots/*.json

Reset statistics

image

What it does

• Clears stats + insights caches (and related report files).

• Next stats/insights load will rebuild from refreshed state.

Best for:

• obviously wrong or stale Dashboard numbers

• after large cleanups, to refresh reports

Does not:

• change provider data or tracker snapshots

Advanced: API details

• Endpoint: POST /api/maintenance/reset-stats

• Default behavior (UI sends {}): purges stats file + state file + reports + insights caches.

• Optional body fields:

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

Notes:

• This is analytics cleanup. It should not affect provider data.

• If recalc=true, it tries to refresh stats from current state.json after purging.

Reset currently playing

image

What it does

• Clears currently_watching.json.

• Removes stuck "currently playing" entries.

Best for:

• UI shows something playing when nothing is playing

Does not:

• remove watched history from any provider

Advanced: API details

• Endpoint: POST /api/maintenance/reset-currently-watching

• Deletes: CW_STATE_DIR/currently_watching.json

Restart CrossWatch

The Restart CrossWatch button restarts the CrossWatch service (container/app) from inside the UI.

• Restarts the backend to reload config and code.

• Avoid restarting during an active sync run.

• Your settings and provider connections are not reset.

This is a hard restart. It’s not graceful. Don’t press it mid-sync unless you like chaos.

Advanced: API details

• Endpoint: POST /api/maintenance/restart

• Behavior: schedules a hard process exit (os._exit(0)) after ~0.75s.

• Your supervisor (Docker restart policy / systemd / etc.) should bring it back.

Advanced: status endpoints

Use these to inspect what CrossWatch sees on disk.

• GET /api/maintenance/provider-cache

  • returns whether it exists, root path, and *.json file list (name/size/mtime)

• GET /api/maintenance/crosswatch-tracker

  • returns resolved tracker root, tracker *.json, snapshot *.json, and counts

Advanced: “Clean Everything” order

The UI runs these in order (after confirmation):

1. POST /api/maintenance/clear-state

2. POST /api/maintenance/clear-cache

3. POST /api/maintenance/clear-metadata-cache

4. POST /api/maintenance/crosswatch-tracker/clear with:

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

1. POST /api/maintenance/reset-stats with {} (defaults to full purge)

2. POST /api/maintenance/reset-currently-watching

If you clicked this by accident, you basically chose “rebuild everything from scratch”.

Advanced: troubleshooting notes

• If “Reset statistics” doesn’t fully clear insights:

  • some caches are best-effort imports; missing modules simply won’t be cleared

  • file patterns are broad on purpose; it cleans “insight-ish” JSON across config/cache/state folders

• If something still looks wrong after a full clean:

  • the problem is likely provider data or mapping logic (not local cache)

Advanced: response format

Most endpoints return JSON like:

• ok: true on success

• ok: false + error on failure

• some include before / after scans and removed lists