FAQ
Quick answers to common CrossWatch questions.
Setup
What is CrossWatch?
CrossWatch syncs watch state between media servers and trackers.
It runs locally and stores state on disk.
Start here: About CrossWatch.
I can’t remember my password
CrossWatch does not have a “forgot password” flow.
If you still have your config, disable UI auth:
Open your
config.jsonin a JSON-aware editor.Set:
"app_auth": {
"enabled": false
}Restart the container.
Log in, then re-enable auth and set a new password.
If you don’t care about keeping any settings/state, delete your config.json.
You will lose your configuration and local state.
Unable to login, but I don’t get a “password incorrect” message
You probably switched between HTTP and HTTPS (or changed hostnames).
That can leave you with a stale auth cookie that never validates.
Delete the CrossWatch site cookies for that URL, then reload and log in again.
If you can’t find it, clear cookies for the whole site or try an incognito window.
Do I need Docker to run CrossWatch?
Yes. CrossWatch is currently distributed as Docker/container images only.
Use a persistent /config mount or you will lose state.
Setup steps: Docker setup.
What port does the UI use?
Default UI port is 8787.
If you change the port mapping, your URL changes too.
Setup reference: Docker setup.
Where does CrossWatch store its data?
CrossWatch stores state as JSON files under your config folder.
In Docker, that is usually /config inside the container.
If you are looking for settings and tokens, start here: Configuration (config.json).
First run
Should I start with syncing or scrobbling?
If you want dataset alignment (watchlists/ratings/history), start with syncing.
If you want plays as they happen, enable scrobbling after.
Decision guide: What do you need?.
What’s the recommended “safe” first setup?
Start with one-way, one pair, one feature.
Default direction is usually media server → tracker.
Baseline defaults: Best practice.
Why do I need a metadata provider (TMDb)?
Better IDs mean better matching.
TMDb reduces “missing peer” issues and bad links.
Setup location: Settings → Metadata. Related: Settings.
Syncing
What is a “pair”?
A pair is a source and a target with a mode and feature toggles.
Left side is Source. Right side is Target.
Deep dive: Configure Pairs.
What direction should I use: tracker → server or server → tracker?
Default is media server → tracker.
Trackers and servers play different roles. Pick a source of truth.
More context: Trackers vs. Media Servers.
Is two-way sync safe?
It can overwrite data. Treat it as an advanced mode.
Start one-way. Move to two-way only after multiple clean runs.
Safety defaults: Best practice.
Can I sync tracker history and ratings into my media server?
You can, but it is usually the wrong direction for history and ratings.
It can create drift and “ghost” history as libraries change.
Why it’s risky: Tracker to Media Server.
Can I sync between two media servers?
Possible, but fragile.
Only do it when libraries are near-identical and you can restore both servers.
Read this first: Media Server to Media Server.
Scrobbling (real-time)
What’s the difference between syncing and scrobbling?
Syncing is periodic dataset alignment (watchlist/history/ratings).
Scrobbling pushes playback progress in real time while you watch.
Overview: Scrobble.
Why don’t media server webhooks work with a self-signed HTTPS certificate?
If your media server must POST webhook events to CrossWatch over https://..., it may reject self-signed certificates.
Webhook delivery will fail.
This affects:
Plex: webhook delivery rejects self-signed TLS certificates.
Emby/Jellyfin: webhook plugins commonly reject self-signed certs unless the CA is trusted.
Fix it by using a reverse proxy with a publicly trusted certificate (example: Let’s Encrypt).
Keep CrossWatch on HTTP behind the proxy.
Related: HTTPS/TLS and Reverse proxies.
Does Watcher require Plex Pass or Emby Premiere?
No. Watcher scrobbles without Plex Pass or Emby Premiere.
Ratings are Plex-only and require an extra helper webhook.
Setup: Watcher.
Scheduling
How do I run CrossWatch automatically?
Enable scheduling in Settings → Scheduling.
Start with a daily cadence. Move to sequential schedules only when needed.
Details: Scheduling.
Troubleshooting and tools
Why didn’t an item sync?
It is usually an ID or matching problem.
Run a sync once, then use Analyzer to see missing peers and missing IDs.
Workflow: Analyzer.
How do I block an item from syncing?
Use Editor → Current State to apply provider-level blocks.
Blocks survive rebuilds because they are stored as policy.
How it works: Editor.
I changed pair direction or enabled new features. What now?
Avoid constant pair changes.
When you do major changes, reset local state so planning recalculates cleanly.
Guidance: Best practice and Maintenance.
What does “Clear state” do?
It deletes the local orchestrator runtime state file (state.json).
Next run becomes a full rebuild.
Details: Maintenance.
Can I export my data to other services?
Yes. Exporter converts your runtime state into import-friendly CSVs.
It does not write back to providers.
How to use it: Exporter.
What are Snapshots?
Snapshots are a local rollback tool.
They capture one provider dataset so you can restore it later.
Details: Snapshots.
Are Snapshots a full backup?
No.
Snapshots do not include CrossWatch config, tokens, or credentials.
They also won’t preserve every provider-side detail (notes, list metadata, etc.).
Where are Snapshots stored?
Snapshots are written under your /config volume:
/config/snapshots/YYYY-MM-DD/
Why is my Plex/Emby/Jellyfin snapshot missing items?
Snapshots follow your library whitelists for that feature.
If you whitelist libraries for History/Ratings/Watchlist, the snapshot includes only those libraries.
Guide: Library Whitelisting.
What’s the difference between “Merge” and “Clear + restore”?
Merge is the safe default. It only adds missing items.
Clear + restore is destructive. It clears the provider dataset first, then restores.
Security and access
How do I enable HTTPS?
Switch the UI protocol to HTTPS, then restart CrossWatch.
You can use self-signed certs or mount custom certs.
Steps: HTTPS/TLS.
Do you support reverse proxy and TLS issues?
Reverse proxy setups and HTTPS/TLS configuration are not in the supported scope.
Issues around proxies, certificates, and the TLS manager get lower priority.
I can’t spend much time debugging these setups. Sorry.
Reference: HTTPS/TLS and Reverse proxies.
Can I install CrossWatch as a phone “app”?
Yes, via PWA install.
You need HTTPS with a trusted certificate (usually via reverse proxy).
Steps: Mobile devices.
Limits and gotchas
Does CrossWatch use a database?
No. CrossWatch stores state as JSON files.
That is simpler, but it caps scale for very large libraries.
Details: About CrossWatch.
Why is my first run slow?
Heavy backfills (full history/ratings) can take a long time.
Prefer incremental windows when possible. Ratings reads are not cached.
Details and guidance: About CrossWatch and Best practice.
Why is my Trakt watchlist missing items?
Trakt Free has tight list limits (watchlist max 100).
SIMKL Free is more forgiving for large watchlists.
Quick comparison: Trakt vs SIMKL (Free plans).
Are there one-off scripts for provider exports or resets?
Yes. There are standalone scripts under /scripts/ inside the container.
If you want a rollback point, prefer the UI tool: Snapshots.
Use /scripts for headless workflows or when you need CLI control.
They are manual tools. Some actions can be destructive.
Read first: Standalone Scripts.
Last updated