# Analyzer
Analyzer helps explain why items do or do not line up between your selected providers.
### What it does
* Reads `state.json` from your latest runs.
* Uses the selected **pair** to show actual sync issues.
* Separates sync problems from background diagnostics.
* Helps you inspect weak or inconsistent IDs.
{% hint style="info" %}
Analyzer does not “fix metadata for you”. It helps you find the right fix faster.
{% endhint %}
### What you need
* At least one recent sync run (so `state.json` exists).
* The pair and feature must be enabled.
Optional, for better suggestions:
* TMDb key (see [Metadata](/crosswatch/providers/metadata.md))
* Trakt app credentials (if you use Trakt lookups)
### What the sections mean
#### `Issues`
These are sync-related problems in the selected pair, such as:
* an item exists on one side but is missing on the other
* an item is blocked by manual rules
* an item is out of scope because of pair settings
* an item has weak or inconsistent IDs that can cause matching trouble
#### `System`
These are background diagnostics about CrossWatch state and provider data, such as:
* broken or stale cache/state files
* unresolved, shadow, flap, blackbox, or watermark problems
* provider/module validation issues
* metadata inconsistencies that may not be causing an active sync problem yet
#### `Scoped`
This is the number of items included for the currently selected pair filter.
#### `Visible`
This is the number of rows currently shown in the top table after search and scope filters are applied.
{% hint style="info" %}
Issues tell you what is wrong in the selected sync path.
System findings help explain why.
{% endhint %}
### How to use it
{% stepper %}
{% step %}
### Run a sync first
Analyzer works from runtime state. Do one normal sync run before you start debugging.
{% endstep %}
{% step %}
### Select the pair you want to inspect
Start with the pair that looks wrong right now.
{% endstep %}
{% step %}
### Look at the top table
Start with actual sync issues in the top table.
{% endstep %}
{% step %}
### Click an item for details
Review the reason details in the lower panel.
{% endstep %}
{% step %}
### Strengthen IDs if needed
Open **Edit Manual IDs** if the item needs stronger IDs.
{% endstep %}
{% step %}
### Use system findings as supporting evidence
Review `System` findings when something still looks wrong after checking the item itself.
{% endstep %}
{% step %}
### Fix at the source, then re-run
For media-server → tracker pairs:
1. Fix IDs in Plex/Jellyfin/Emby.
2. Refresh metadata if needed.
3. Re-run the pair.
4. Confirm the issue disappears.
{% endstep %}
{% endstepper %}
### Where to fix issues
In almost all setups, fix the **source of the pair**.
Media server → tracker:
* Fix IDs and matching in Plex/Jellyfin/Emby.
* Re-run the pair.
Tracker-only items:
* Analyzer does not edit trackers directly.
* Clean it up in the tracker, or import it to your media server.
### Issue types (reference)
Common issue types
* `missing_peer`: item exists on source, but no match exists on the target for this pair.
* `missing_ids`: core IDs (IMDb/TMDb/TVDb) are missing.
* `invalid_id_format`: ID format is wrong (example: IMDb missing `tt`).
* `key_missing_ids`: key claims an ID, but the ID field is empty.
* `key_ids_mismatch`: key says one ID, field says another.
{% hint style="warning" %}
Suggestions are hints, not guarantees. Sanity-check before trusting them.
{% endhint %}
### UI guide (quick)
* **Pair selector**: focus on one selected pair.
* **Issues**: actual sync problems for that pair.
* **System**: supporting diagnostics and state warnings.
* **Top table**: sort and search by provider, feature, title, year, and type.
* **Detail panel**: shows likely cause and suggestions.
* **Edit Manual IDs**: lets you test stronger IDs locally.
* **Scoped**: items included for the selected pair filter.
* **Visible**: rows still shown after search and scope filters.
Related: [Editor](/crosswatch/tools/editor.md).
Screenshots
### Troubleshooting
* **Scoped looks wrong**: check the selected pair and pair settings.
* **Visible looks too low**: clear search or other active filters.
* **No suggestions**: add TMDb metadata, or connect Trakt for richer lookups.
* **System findings keep appearing**: inspect local state freshness, provider health, and cache behavior.
* **Same issue returns after sync**: source metadata is still wrong. Fix IDs/year and re-run.
---
# 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/tools/analyzer.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.