FAQ

Common questions about installation, setup, syncing, scrobbling, and troubleshooting.

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.

I can’t remember my password

CW does not have a “forgot password” flow.

If you still have your config, disable UI auth:

1. Open your config.json in a JSON-aware editor.

2. Set:

"app_auth": {
  "enabled": false
}

1. Restart the container.

2. 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 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.

If you want NAS/Portainer-specific steps, start here: Container installation.

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 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).

Which services are supported?

Media servers: Plex, Jellyfin, Emby.

Trackers: Trakt, SIMKL, MDBList, AniList.

Full list: 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?.

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.

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.

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 and 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.

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

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.

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 and 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.

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

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.

Should I use Watcher or Webhooks?

Use Watcher.

Legacy webhooks are deprecated and not maintained.

How to pick: 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 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.

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.

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.

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.

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

• If you can, run the capture from a direct LAN URL (no proxy) to confirm it’s proxy-only.

Reference config: Reverse proxies. Captures guide: 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.

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 practices 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.

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 and 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.

What are Captures?

Captures are a local rollback tool.

They capture one provider dataset so you can restore it later.

Details: 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.

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.

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.

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

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.

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.

How-to: Multiple containers (full isolation).

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 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).