Maintenance

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

Maintenance controls logging, cleanup, and service restarts for CrossWatch (CW). 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.

These actions are local to CW. 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 CW 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 CW 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.

• CW 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.

When to clear state or provider cache

Do not clear cache between normal syncs.

This is a repair step. It is not routine maintenance.

Clear state + provider cache together when:

• you switch a pair between one-way and two-way

• you update CrossWatch and the next plan looks wrong

• you backfill history using old dates and new items do not appear

• a run wants to remove far more items than expected

Why these cases matter:

• Mode switch: old baselines can use a different key shape than the new mode expects.

  • On the first two-way run, that can look like false deletions.

• After an update: adapter refactors can change keys, ID normalization, or episode grouping.

  • Old cache files may no longer match current provider output.

• Historical backfill: older watermark files can miss items added with old timestamps.

  • Current builds handle this better, but older cache files may still need one reset.

• Unexpected mass removes: stop immediately.

  • Restore from the provider’s own undo/history first.

  • Then reset local state before trying again.

If the first run after a config change wants to delete a lot of items, do not “see what happens”.

Stop, restore on the provider side if needed, clear local state/cache, then rerun in dry run.

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

• switching a pair between one-way and two-way when planning looks wrong

Does not:

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

• delete CW 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

• CW reusing obviously old provider data

• clearing tombstones, watermarks, and provider-side index cache files after a bad plan

• pairing with Clear state for the safest sync reset

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.

What each reset clears

Use this when you are cleaning files manually, or when you want to know what the UI buttons are rebuilding.

Clear state removes:

• state.json

  • clears provider baselines

  • clears old mode-transition memory

Clear provider cache typically removes files under .cw_state/, including:

• tombstones.json

  • clears deletion memory that can block re-adds or drive removes

• *.flap.json

  • clears previous snapshot/failure tracking

• *.index.*.json and *.cache.*.json

  • clears provider-specific index caches

• *.watermarks.*.json

  • forces a full refetch instead of delta

Safest full reset

For the cleanest rebuild:

1. Run Clear state

2. Run Clear provider cache

3. Rerun with Dry run first

4. Start with one pair and one feature if you are debugging

If you are cleaning files by hand, deleting state.json plus everything in .cw_state/ is the safest full reset.

The next run will be slower. It will rebuild from live provider data instead of old local cache.

Routine delta caching, watermarks, and tombstones are correct in steady state.

Only clear them when you are fixing a bad plan or recovering from a major change.

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 CW tracker

image

The CW 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 CW

The Restart CrossWatch button restarts the CW 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 CW 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