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.
CrossWatch is not the right tool for very large libraries.
If your volumes are outside the recommended ranges, do not force it. Check Limitations first.
Default setup (recommended)
Direction: Media server -> tracker
Watchlist: start one-way. Optional: 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)
Do not switch to tracker -> media server unless you have a clear reason.
Trackers often contain items your server does not have.
That means History and Ratings can fail, stay unresolved, or create noisy plans.
For most setups, only sync data into a media server when the item already exists in that library.
Related: Trackers vs. Media Servers and Tracker to Media Server
CrossWatch supports real bidirectional synchronization. Changes on either platform can sync in both directions.
That adds flexibility. It also adds risk.
Because both sides can introduce changes, you are more likely to see:
conflicts
duplicate items
unintended overwrites
propagated deletions
This gets worse when a provider returns delayed, partial, or inconsistent data.
Use bidirectional sync carefully.
It may look like the better option. For most users, one-way sync is still the safer and more predictable setup.
Golden rules
Pick a source of truth for each pair.
Expect conflicts.
Source wins on conflicts.
Start with one pair and one feature.
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.
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 and provider cache
Reset both when you make a major sync change or the next plan looks unsafe.
Common triggers:
You switch one-way ↔ two-way
You change library filters or whitelists on an active pair
You update CrossWatch and the first plan looks wrong
You backfill history with old dates and the provider uses delta reads
You see an unexpected large remove plan
If a run wants to remove far more than expected:
Stop
Restore from the provider’s own undo/history if needed
Clear local state and provider cache
Rerun in Dry run
When to avoid resetting
You only changed schedules.
You only changed logging levels.
You only changed UI/runtime preferences that do not affect data.
Normal syncs look correct and item counts are stable
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.
After a reset, treat the next run like a first run.
Use Dry run. Start with one pair and one feature.
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
Limitations - when CrossWatch is the wrong tool for the job
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?