> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/getting-started/limitations.md).

# Limitations

Soft size guidance, provider plan limits, and request-throttling limits that affect CrossWatch behavior.

CrossWatch is **not** built for very large libraries.

It is a UI-first tool with metadata enrichment, images, and safety checks.

**It is not a bulk-sync engine.** Big libraries create heavy API traffic and large JSON files.

For large libraries, try the [CrossWatch CLI](https://wiki.crosswatch.app/crosswatch/command-line-interface-cli.md) for syncs and monitoring.

### Profiles and connections

* **Instances per provider**: `10` by default, including the default connection
* **Profiles**: no limit
* **Instance name**: `12` characters max
* **Profile name**: `40` characters max

The instance limit counts per provider. Emby, Jellyfin, Plex, the CrossWatch tracker and every other provider each get their own `10`.

The limit is there for a reason. Every instance keeps its own state, cache and snapshots, and each sync pair using it reads that provider again. More instances mean more memory, more CPU, more disk use and longer sync runs. You can easily go past the sizes this page is based on.

For several people on the same media servers, use [Identities](https://wiki.crosswatch.app/crosswatch/settings/connections/media-servers/multiple-media-server-users.md). One connection can include up to 25 identities by default. Separate tracker accounts still need separate instances.

{% hint style="info" %}
You can raise the limit in `config.json` under `runtime`, up to `100`. Restart CrossWatch afterwards.

`"max_profiles_per_provider": 25`

Raising it is at your own risk. Keep an eye on memory and sync times.
{% endhint %}

### Size guidance

These are **approximate** limits.

The tighter limits below are about API pressure and JSON file sizes

CW recommends these rough upper bounds for normal use:

* **Watchlist**: `~2,500`
* **Progress**: `~2,500`
* **History**: `~25,000`
* **Ratings**: `~25,000`
* **Collections**: `~25,000`

{% hint style="info" %}
Synchronization is **memory and CPU intensive** because large datasets need to be loaded, compared and processed to determine what has changed. This includes matching records, calculating differences, resolving conflicts and transforming data between systems.
{% endhint %}

### CPU usage

The figures below are illustrative examples, not performance guarantees.

<table><thead><tr><th width="88.66668701171875">Items</th><th align="right">Idle</th><th align="right">While syncing</th><th align="right">Peak</th><th align="right">First sync</th><th align="right">Later syncs</th></tr></thead><tbody><tr><td>2,500</td><td align="right">1 to 2 %</td><td align="right">~85 %</td><td align="right">~120 %</td><td align="right">~5 s</td><td align="right">~3 s</td></tr><tr><td>25,000</td><td align="right">1 to 2 %</td><td align="right">~85 %</td><td align="right">~120 %</td><td align="right">~85 s</td><td align="right">~26 s</td></tr><tr><td>50,000</td><td align="right">1 to 2 %</td><td align="right">~85 %</td><td align="right">~120 %</td><td align="right">~170 s</td><td align="right">~55 s</td></tr></tbody></table>

Percentages are of a single core, as reported by docker stats. 100% means one core fully busy.\
Actual CPU use and sync times depend on the provider, enabled features, options, and hardware. Some providers make requests concurrently.

The first sync compares the selected data on both sides and writes the changes allowed by the pair. Later runs use saved state to identify changes. Idle covers the scheduler and the web UI sitting there with no sync running.

### Memory usage

| Items  | Minimum |   Average |   Maximum | Idle after sync |
| ------ | ------: | --------: | --------: | --------------: |
| 2,500  |  88 MiB |  \~95 MiB | \~105 MiB |        \~95 MiB |
| 25,000 |  88 MiB | \~230 MiB | \~330 MiB |       \~225 MiB |
| 50,000 |  88 MiB | \~350 MiB | \~570 MiB |       \~370 MiB |

Measured container memory, excluding Docker Desktop overhead. Minimum is a fresh start before any sync. Maximum is reached while syncing with the Analyzer and dashboard pages open. Memory use varies between runs and providers.

Figures assume one pair. Each extra pair adds its own peak, and real providers add roughly 30 MiB on the first sync for TLS connections and provider sessions.\
\
If you're concerned about CPU or memory usage, use [Container Run Once Mode](https://wiki.crosswatch.app/crosswatch/command-line-interface-cli/container-run-once-mode.md) for scheduled syncs. See [Docker setup](https://wiki.crosswatch.app/getting-started/installation/docker-setup.md) for container configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/getting-started/limitations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
