> 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/crosswatch/settings/connections/media-clients/kodi/kodi-add-on/troubleshooting-and-reporting.md).

# Troubleshooting and reporting

Diagnose delivery, viewer, playlist, and rating problems.

### Nothing arrives in CrossWatch

1. Check **Status**. Pair when it reads **Not paired**.
2. Check `kodi.log`. `reporter.failed` means Kodi cannot reach CrossWatch. `CERTIFICATE_VERIFY_FAILED` means the HTTPS certificate is not publicly trusted. `reporter.rejected` with `status=401` means CrossWatch rejected the token. Pair again.
3. Confirm the Kodi add-on is enabled for this Kodi profile in CrossWatch. Re-enable it, then pair again.
4. Only episodes and films with a real ID are reported. PlexKodiConnect playback is skipped by default.
5. Finished watches are kept while CrossWatch is unavailable. Other events are retried for two minutes only.

Pairing again after a token change discards finished watches queued for the old token.

### Viewer issues

#### Playback has no viewer or the wrong viewer

Check that the viewer name matches the route's **Username whitelist**. For a route without a whitelist, it must match the assigned user profile.

With two or more viewers, playlists, profiles, or the end-of-playback question must identify someone. Playlists override remembered answers. Do not use progress-based playlists.

#### No CrossWatch route

Confirm that a Kodi watcher route exists. Add the viewer to its username whitelist, or assign the route to the matching user profile without a whitelist. Updates appear within five minutes.

#### A person is missing from Add viewer

The picker lists only user profiles assigned to an unwhitelisted route for this Kodi. It excludes people already configured as viewers. Wait for the next check-in, then reopen the Viewers window.

Older CrossWatch releases do not list people. Use **Type a name** instead.

#### Playlist or profile missing

The Kodi item was renamed or removed. Open that viewer's playlists or profiles, remove the missing item, and select its replacement. A missing playlist disables all playlist matching for that viewer.

An unusable playlist is not a TV-show or film smart playlist. Remove it, or change its Kodi type.

### Ratings

Ratings are off by default. If enabled, Kodi still asks only for finished, reported items.

| Log line                                            | Meaning                                                     |
| --------------------------------------------------- | ----------------------------------------------------------- |
| `reporter.rejected` with `reason=unsupported_event` | CrossWatch is too old for ratings. Update it.               |
| `reporter.rejected` with `reason=no_rating_target`  | No matching route accepts that rating type.                 |
| `reporter.rejected` with `reason=no_matching_route` | No route accepts the viewer.                                |
| `reporter.rated` with `failed=` above 0             | A destination refused the rating. Check the CrossWatch log. |

### Logs

Normal failures, refusals, and check-ins go to Kodi's `kodi.log`. See the [Kodi log-file guide](https://kodi.wiki/view/Log_file) for its location.

Enable debug logging for `crosswatch.log`. Kodi stores it in `userdata/addon_data/service.crosswatch/logs/`. Other Kodi profiles use `userdata/profiles/<profile>/`. The log is capped at 500 KB plus three older files, uses UTC timestamps, and includes titles and viewer names.

Neither log includes webhook tokens or pairing codes. Kodi's own debug logging can record a one-time Link code after it has been used.

### What the add-on sends

The add-on sends playback starts, pauses, resumes, progress, and stops for films and episodes. It also sends a heartbeat every five minutes, viewer names after configuration changes, and enabled ratings.

Events include viewer identification, item metadata and IDs, playback position, a sanitized file path, Kodi device details, and add-on version. The webhook token is sent in a request header, never in a URL.

Only episodes and films with at least one real ID are reported. Music, live TV, and unrecognised files are excluded. See the [event contract](https://github.com/crosswatch-app/kodi-addon/blob/main/docs/contract.md) for the payload.

#### When CrossWatch is unavailable

The add-on retries each event for two minutes. Completed watches and ratings are stored locally, retried every five minutes, and retried after Kodi starts. They keep their original event time.

A queued item is dropped when CrossWatch refuses it, it is over seven days old at Kodi startup, more than 200 are waiting, or its token changes. Queued records live in `outbox.json` inside the add-on data folder.

### Get help

Open an issue at [crosswatch-app/kodi-addon](https://github.com/crosswatch-app/kodi-addon/issues). Attach `kodi.log` and `crosswatch.log` if available. Review both first for information you do not want to share.


---

# 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/crosswatch/settings/connections/media-clients/kodi/kodi-add-on/troubleshooting-and-reporting.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.
