Best practices
Recommended defaults for safe syncing, conflict handling, and operational hygiene.
Use these defaults unless you have a reason to deviate.
This page looks long because it covers edge-cases. Most users do not need to change much. If you want a safe setup, follow the defaults below. Start with one pair and one feature.
CrossWatch (CW) is safest when you start small and keep runs predictable.
Default setup (recommended)
Direction: Media server -> tracker
Watchlist: start one-way. Move to two-way after clean runs.
History: do a one-way seed once. Then disable History and use scrobbling.
Ratings: keep one-way (server -> tracker)
Snapshots: enable the internal CW Tracker mod
Security: enable HTTPS/TLS and UI authentication
Two-way sync can overwrite data. Back up first. Test your restore.
Golden rules
Pick a source of truth for each pair.
Expect conflicts.
Source wins on conflicts.
Start with one pair and one feature.
Use Dry run before applying changes.
Enable only what you need.
Default conflict policy:
If both sides changed an item, keep Source.
If Source removed and Target added, treat it as remove.
Metadata agents (recommended)
Good metadata is the difference between stable ID matching and messy title guessing.
Use these defaults:
Plex Media Server: use the default Plex Movie and Plex TV Series metadata agents.
Emby and Jellyfin: use TMDb metadata.
Watchlists
Watchlists are the safest feature to run two-way. Still start one-way.
Two-way is only sane when:
IDs are stable on both sides (TMDb/TVDB/IMDb).
You have multiple clean runs.
You tested adds and deletes in both directions.
Optional:
Use a short grace period for just-added or just-removed items.
This reduces churn during premieres and rematches.
History
Default: Media server -> tracker.
Recommended workflow:
Run History one-way once to seed the tracker.
Disable History in the pair.
Enable scrobbling for new plays.
Avoid enabling Remove for History. It only makes sense in niche cases.
Ratings
Default: Media server -> tracker.
Avoid two-way unless you accept noise:
Providers disagree on episodes, specials, and editions.
Rating scales differ (1–10 vs stars/hearts).
If you do two-way:
Pick a source of truth.
Align scales and rounding.
Changing pairs and resets
Do not constantly tweak direction, mode, or enabled features. If you do, reset state so planning recalculates cleanly.
When to reset state & stats
You changed pair direction or mode (one-way <-> two-way).
You enabled a new feature on an existing pair.
You changed provider credentials.
You changed library filters or whitelists.
You merged, split, or rebuilt pairs.
When to avoid resetting
You only changed schedules.
You only changed logging levels.
You only changed UI/runtime preferences that do not affect data.
Resetting clears the planner memory. The next run rebuilds deltas from zero.
With delta providers (example: SIMKL), avoid frequent resets. They defeat incremental syncing. They may also increase API pressure and risk throttling.
Scheduling
Avoid overlaps.
Keep runs predictable.
Debugging
Use normal logs day to day.
Enable debug only while investigating.
Use Analyzer for missing IDs and broken matches.
Use Editor for manual policy and blocking.
Related topics
Trackers vs. Media Servers - pick a sane source of truth
Tracker to Media Server - why the direction is risky
Media Server to Media Server - why cross-sync is fragile
Syncing - the step-by-step setup
Webhook or Watcher - scrobbling setup
Summary
Start one-way. Prefer media server -> tracker.
Seed History once. Then rely on scrobbling.
Use dry runs, backups, and a clear source of truth.
Next steps
Set up your pair toggles and safety controls: Configure Pairs.
Configure predictable runs and avoid overlaps: Scheduling.
Turn on real-time plays after the first history seed: Watcher.
Debug mismatches and missing IDs: Analyzer.
Last updated
Was this helpful?