# Migrate to routes mode

Routes mode replaces the legacy `provider + sink` Watcher config.

Before **v0.9.0**, Watcher used the legacy fields.

Starting with **v0.9.0**, Watcher uses routes mode.

As of **v0.9.15**, CrossWatch no longer auto-migrates legacy Watcher config.

If you upgrade from an old config, you must create routes yourself.

Starting with a clean `config.json` is usually the best option.

It lets you scrobble:

* multiple media servers in parallel
* to multiple trackers
* with per-route filters

### Legacy config (pre-v0.9.0)

Legacy Watcher config used:

* `scrobble.watch.provider`
* `scrobble.watch.sink` (sometimes CSV)
* `scrobble.watch.filters`

### Routes config (v0.9.0+)

Routes mode uses:

* `scrobble.watch.routes[]`

Each route is one mapping:

`provider(profile) → sink(profile)`

Each route can also have its own **Filters** and **Options**.

Global Watcher settings still exist.

They act as the defaults for every route.

If one route needs different behavior, override it in that route instead of changing the global default for everything.

### What to do in v0.9.15+

There is no automatic conversion anymore.

If your old config still uses the legacy Watcher fields, rebuild the Watcher routes manually.

Preferred path:

* start with a clean `config.json`
* reconnect the providers you need
* recreate your routes in the UI

If you keep an existing config:

* treat the old Watcher fields as legacy only
* recreate each route by hand
* re-check filters, profiles, and route options carefully

### Checklist

1. Decide whether to start clean or keep the old `config.json`.
2. Prefer a clean `config.json` if you want the least confusing setup.
3. Open **Settings → Scrobble → Watcher**.
4. Confirm you see a **Routes** section.
5. Recreate each route with the right provider and sink.
6. Leave the global Watcher settings alone unless you want a different default for all routes.
7. If you use profiles:
   * create the needed provider profiles
   * update each route’s `provider_instance` / `sink_instance`
8. Set route **Filters** so the route only matches the users or server you want.
9. Use route **Options** only when one route should behave differently.
10. Start Watcher.
11. Check status in the UI.

### Common issues

#### Routes duplicated

A route is identified by:

`provider + provider_instance + sink + sink_instance`

If you duplicate that tuple, you will double-scrobble.

Keep the filters and options in mind too.

Two near-identical routes can still create confusing results.

#### Watcher runs but nothing scrobbles

* Check auth for the selected sink profile.
* Check that your routes were recreated correctly.
* Tighten filters. Empty filters are safest to validate first.

### Related

* Configure Watcher: [Watcher](/crosswatch/scrobble/watcher.md)
* Provider profiles: [Profiles](/crosswatch/profiles.md)


---

# 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/scrobble/watcher/migrate-to-routes-mode.md?ask=<question>
```

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.