# FAQ Quick answers to common CrossWatch (CW) questions. ### Setup
What is CW? CW syncs watch state between media servers and trackers. It runs locally and stores state on disk. Start here: [About CrossWatch](https://wiki.crosswatch.app/getting-started/about-crosswatch).
I forgot my username or password CW has a recovery flow. 1. Set as env `CW_RESET_AUTH_ONCE=1` on the container. 2. Start container 3. Complete credential setup again. 4. Remove `CW_RESET_AUTH_ONCE` after the reset finishes. If that does not work, disable UI auth in `config.json`: 1. Open `config.json` in a JSON-aware editor. 2. Set: ```json "app_auth": { "enabled": false } ``` 3. Restart the container. 4. Log in. 5. Re-enable UI auth and create new credentials.
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 CW 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 CW? Yes. CW is currently distributed as Docker/container images only. Use a persistent `/config` mount or you will lose state. Use the same image, port mapping, and persistent `/config` mount in Portainer or your NAS UI. Setup steps: [Docker setup](https://wiki.crosswatch.app/getting-started/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](https://wiki.crosswatch.app/getting-started/docker-setup).
Where does CW store its data? CW 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)](https://wiki.crosswatch.app/crosswatch/configuration-config-json).
Which services are supported? Media servers: Plex, Jellyfin, Emby. Trackers: Trakt, SIMKL, MDBList, AniList. Full list: [Providers](https://wiki.crosswatch.app/crosswatch/providers).
### 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?](https://wiki.crosswatch.app/getting-started/first-time-setup/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 practices](https://wiki.crosswatch.app/getting-started/best-practices).
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](https://wiki.crosswatch.app/crosswatch/navigation/settings).
What metadata should I use on my media server? CW matches best when your media server stores stable external IDs (TMDb/IMDb/TVDb). Use these defaults: * **Plex Media Server**: use the default **Plex Movie** and **Plex TV Series** metadata agents. * **Emby** and **Jellyfin**: use **TMDb** metadata for Movies and Series. After changing metadata settings, refresh metadata so IDs get populated. Related: [Best practices](https://wiki.crosswatch.app/getting-started/best-practices) and [Metadata](https://wiki.crosswatch.app/crosswatch/providers/metadata).
### 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](https://wiki.crosswatch.app/crosswatch/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](https://wiki.crosswatch.app/related-information/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 practices](https://wiki.crosswatch.app/getting-started/best-practices).
I have two-way sync, but when I delete something it gets instantly re-added That usually means deletes are not enabled for that feature. Edit the pair and enable the feature’s delete toggle: * **Watchlist** → enable **Remove** * **Ratings** → enable **Remove (clear)** If **Remove** is off, CW treats your deletion as drift and adds it back.
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](https://wiki.crosswatch.app/related-information/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](https://wiki.crosswatch.app/related-information/media-server-to-media-server).
I ran a history sync and it says X items unresolved. Did the sync fail? No. A run can complete successfully with `unresolved > 0`. “Unresolved” means CrossWatch found history entries in the source. It could not write a safe equivalent entry on the destination. Common reasons (History): * **Missing timestamp**\ The destination requires `watched_at`, but the source entry has no usable date/time. * **Not a playable item**\ Some sources emit show/season roll-ups. Many destinations only accept movie/episode history. * **Can’t match the item**\ No stable ID match. Or the destination library does not contain that item/version. Common log codes: * `skip_missing_date`\ The entry had no usable watch date/time, so it was skipped. * `resolve_failed`\ CrossWatch could not find a definite destination match. It did not apply the entry. Related: [Sync results](https://wiki.crosswatch.app/getting-started/first-time-setup/what-do-you-need/syncing/sync-results) and [Unresolved](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/unresolved).
Does “unresolved” mean my watch history is wrong now? Not necessarily. Unresolved entries are typically entries the destination can’t represent anyway. Most of the “good” history (episodes/movies with timestamps) still writes fine.
How can I check if the sync did what I wanted? Spot-check a few items you know you watched in the source. Confirm they show as watched/played in the destination. If those match, the sync likely did its job.
What’s the best way to use history sync long-term? Use history sync as a one-time seed. After that, rely on normal tracking going forward (scrobbling / play tracking). Avoid repeatedly re-importing full history unless you are intentionally rebuilding.
Can I reduce unresolved items? Sometimes. Start with matching hygiene: * Ensure both sides have stable external IDs (TMDb/IMDb/TVDb), when supported. See: [Metadata](https://wiki.crosswatch.app/crosswatch/providers/metadata). * Ensure the destination library contains the content you are importing. * Prefer episode/movie-level history over show/season roll-ups. To debug specific misses, run: [Analyzer](https://wiki.crosswatch.app/crosswatch/tools/analyzer).
### 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](https://wiki.crosswatch.app/crosswatch/scrobble).
Should I use Watcher or Webhooks? Use **Watcher**. Legacy webhooks are deprecated and not maintained. How to pick: [Webhook or Watcher](https://wiki.crosswatch.app/getting-started/first-time-setup/what-do-you-need/webhook-or-watcher).
Why don’t media server webhooks work with a self-signed HTTPS certificate? If your media server must `POST` webhook events to CW 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 CW on HTTP behind the proxy. Related: [HTTPS/TLS](https://wiki.crosswatch.app/crosswatch/navigation/ui-settings/user-interface/https-tls) and [Reverse proxies](https://wiki.crosswatch.app/related-information/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](https://wiki.crosswatch.app/crosswatch/scrobble/watcher).
I see no Playing Card The Playing Card is the “Now Playing” footer widget. It shows only when: * **Settings → UI → Playing Card** is enabled. * You configured **TMDb** in **Settings → Metadata**. Then start playback on your media server.
Which trackers can Watcher scrobble to? Watcher targets Trakt, SIMKL, and MDBList. You can choose one or multiple sinks. Setup: [Watcher](https://wiki.crosswatch.app/crosswatch/scrobble/watcher).
### Scheduling
How do I run CW automatically? Enable scheduling in Settings → Scheduling. Start with a daily cadence. Move to sequential schedules only when needed. Details: [Scheduling](https://wiki.crosswatch.app/crosswatch/scheduling).
### Troubleshooting and tools
Why does my password manager show popups or autofill prompts in CrossWatch? Some password managers inject autofill and “save” overlays. This can break API key and token fields in CrossWatch. Fix: 1. Add your CrossWatch URL to the password manager’s **excluded / never autofill** sites list. 2. Reload CrossWatch. 3. Re-enter the value manually. This stops the extension from interfering with protected configuration fields.
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](https://wiki.crosswatch.app/crosswatch/tools/analyzer).
I get a reverse proxy timeout (504 Gateway Timeout) This is almost always a timeout limit in front of CrossWatch. This happens most often in **Captures**. Captures can be slow on large Plex libraries. There are two separate “timeout bombs”: * **Frontend hard timeout**: the web UI aborts API calls after \~`180s` (3 minutes). * If a Plex call takes longer, your browser stops waiting. * The backend may still be working. * **Proxy timeouts**: many reverse proxies default to \~`60–120s` read timeouts. * Long-running HTTP requests die mid-flight. Fix: * Increase reverse proxy timeouts. * NGINX: `proxy_read_timeout` and `proxy_send_timeout` * Reduce how much data Captures has to scan. * Captures follow your per-feature library whitelists. * Guide: [Library Whitelisting](https://wiki.crosswatch.app/crosswatch/library-whitelisting) * If you can, run the capture from a direct LAN URL (no proxy) to confirm it’s proxy-only. Reference config: [Reverse proxies](https://wiki.crosswatch.app/related-information/reverse-proxies). Captures guide: [Captures](https://wiki.crosswatch.app/crosswatch/tools/captures).
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](https://wiki.crosswatch.app/crosswatch/tools/editor).
I changed pair direction or enabled new features. What now? Avoid constant pair changes. If you switch **one-way ↔ two-way**, change active library filters, or upgrade CrossWatch and the next plan looks wrong, clear **state** and **provider cache** together. That removes old baselines, tombstones, and watermarks that can distort the next run. Then rerun in **Dry run** first. Guidance: [Best practices](https://wiki.crosswatch.app/getting-started/best-practices) and [Maintenance](https://wiki.crosswatch.app/crosswatch/maintenance).
When should I clear state and provider cache? Use it as a repair step. Do not do it between normal syncs. Clear both when: * you switch **one-way ↔ two-way** * you update CrossWatch and the first plan looks wrong * you backfill history with old dates and items are missed * a run wants to remove far more items than expected If you see a surprise mass-remove plan: 1. Stop the run 2. Restore from the provider’s own undo/history if needed 3. Clear state and provider cache 4. Rerun in **Dry run** Details: [Maintenance](https://wiki.crosswatch.app/crosswatch/maintenance).
What does “Clear state” do? It deletes the local orchestrator runtime state file (`state.json`). Next run becomes a full rebuild. Details: [Maintenance](https://wiki.crosswatch.app/crosswatch/maintenance).
What should I do after I clear state or provider cache? Clearing state/cache makes the next run behave like a first run. To stay in control: 1. Disable temporary scheduling (so nothing auto-runs). 2. If you have multiple features enabled, run them separately. This keeps the blast radius small and makes debugging easier. Related: [Maintenance](https://wiki.crosswatch.app/crosswatch/maintenance) and [Best practices](https://wiki.crosswatch.app/getting-started/best-practices).
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](https://wiki.crosswatch.app/crosswatch/tools/exporter).
What are Captures? Captures are a local **rollback tool**. They capture one provider dataset so you can restore it later. Details: [Captures](https://wiki.crosswatch.app/crosswatch/tools/captures).
Are Captures a full backup? No. Captures do not include CW config, tokens, or credentials. They also won’t preserve every provider-side detail (notes, list metadata, etc.).
Where are Captures stored? Captures are written under your `/config` volume: `/config/snapshots/YYYY-MM-DD/`
Why is my Plex/Emby/Jellyfin capture missing items? Captures follow your **library whitelists** for that feature. If you whitelist libraries for History/Ratings/Watchlist, the capture includes only those libraries. Guide: [Library Whitelisting](https://wiki.crosswatch.app/crosswatch/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
Should I expose CW to the public internet? No. Use a VPN or a reverse proxy with authentication. Security guidance: [Disclaimer](https://wiki.crosswatch.app/related-information/disclaimer).
How do I enable HTTPS? Switch the UI protocol to HTTPS, then restart CW. You can use self-signed certs or mount custom certs. Steps: [HTTPS/TLS](https://wiki.crosswatch.app/crosswatch/navigation/ui-settings/user-interface/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](https://wiki.crosswatch.app/crosswatch/navigation/ui-settings/user-interface/https-tls) and [Reverse proxies](https://wiki.crosswatch.app/related-information/reverse-proxies).
Can I install CW as a phone “app”? Yes, via PWA install. You need HTTPS with a trusted certificate (usually via reverse proxy). Steps: [Mobile devices](https://wiki.crosswatch.app/crosswatch/navigation/mobile-devices).
### Limits and gotchas
Does CW use a database? No. CW stores state as JSON files. That is simpler, but it caps scale for very large libraries. Details: [About CrossWatch](https://wiki.crosswatch.app/getting-started/about-crosswatch).
Can I connect multiple users or multiple servers? Yes. Use **profiles** in **Settings → Authentication**. Click **Profile** on a provider to add one. Each profile is a fully separate connection. You still need to do the full connect + settings + save flow. CrossWatch creates the next available `PROVIDER-P##` ID automatically. Then pick that profile in: * **Pairs** (`source_instance` / `target_instance`) * **Watcher routes** (`provider_instance` / `sink_instance`) Warning: profiles can get complicated fast. If you delete a profile, also delete or update any pairs/routes that reference it. Guide: [Profiles](https://wiki.crosswatch.app/crosswatch/profiles). If you want full isolation (separate UI, separate state), run multiple containers. Rules: * Use a different **host port** per container. * Use a separate **`/config`** per container. Start from [Docker setup](https://wiki.crosswatch.app/getting-started/docker-setup) for each container.
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](https://wiki.crosswatch.app/getting-started/about-crosswatch) and [Best practices](https://wiki.crosswatch.app/getting-started/best-practices).
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)](https://wiki.crosswatch.app/related-information/trakt-vs-simkl-free-plans).
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://wiki.crosswatch.app/crosswatch/faq.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.