Game Watcher Troubleshooting

API-Fehlercodes im Klartext

Der Ingest-Endpoint antwortet bei fachlichen Fehlern bewusst mit HTTP 200 — das ist Absicht, damit dein Watcher nicht in eine Retry-Schleife läuft. Prüfe immer das ok-Feld im Body, nicht nur den HTTP-Status.

HTTP	code	Bedeutung / Fix
200	`accepted`	Alles gut, `event_id` im Response.
200	`replay_ignored`	Serverseitiger Dedupe hat zugeschlagen — kein Fehler, meist nach Watcher-Neustart mit Log-Re-Tail.
200	`source_not_allowed`	Dein `source`-Feld ist nicht in der Allowlist. Die Allowlist ist größer als früher hier dokumentiert (über 120 Werte aus `EventNormalizer::ALLOWED_SOURCES` + `TelemetryProfileCatalog::WATCHER_REGISTRY`, s. Einrichten-Seite) — häufigster Fehler bei eigenen Integrationen bleibt trotzdem ein frei erfundener Wert. Bei Custom-Scripts auf `generic-log`/`generic-json` umstellen.
200	`event_type_required`	`event`/`event_type` fehlt oder passt nicht auf `^[a-z][a-z0-9_]{0,63}$`.
200	`occurred_at_in_future`	Zeitstempel mehr als 10 Minuten in der Zukunft — Systemuhr auf dem Watcher-Rechner prüfen.
200	`occurred_at_too_old`	Zeitstempel mehr als 24h in der Vergangenheit (Backdate-Limit).
200	`channel_not_owned`	`channel_id` gehört nicht zu deinem Account — Feld weglassen oder korrekte ID aus dem Dashboard nehmen.
200	`rate_limited_per_token`	Innerer Per-Token-Bucket leer (200 Burst, 10/s). `hint` nennt `retry_after_sec`. Auf Client-Seite batchen/drosseln.
401	`pat_required`	Kein oder ungültiger Bearer-Token. Neuen PAT im Dashboard erstellen.
403	`scope_required`	Token hat nicht den Scope `game_watcher`. Anderer Scope funktioniert hier nicht — neuen Token mit korrektem Scope anlegen.
413	`payload_too_large`	Body über 64 KB. Bei generic-json/generic-log: weniger Metadata pro Event schicken.
429	`rate_limited`	Äußeres IP-Limit (600 Burst/10/s), unabhängig vom Token-Limit.
500	`ingest_failed`	Server-/DB-Problem, nicht dein Payload. Kurz warten, dann erneut versuchen; hält es an, Support kontaktieren.

"Watcher offline" im Dashboard, obwohl der Watcher läuft

Nutzt du den Standalone-Watcher? Korrektur: Er schickt seit V1.2 ebenfalls einen Heartbeat (alle 30s per PAT an POST /v1/integrations/game-watcher/heartbeat, Quelle: dem Game-Watcher). Zeigt das Dashboard trotzdem "offline", prüfe: Token gültig/Scope korrekt, apiBase erreichbar, kein Dry-Run aktiv (PASTE_LOCAL_TOKEN_HERE in der Config), Firewall/Antivirus blockiert nicht die ausgehende Verbindung.
Nutzt du Chatlix Connect: Tray-Icon vorhanden? Game-Watcher-Modul in den Connect-Settings aktiv?
Firewall/Antivirus blockiert https://api.chatlix.app?

"Token invalid" / 401 / 403

Token-Scope ist game_watcher? Über Profil → API-Tokens prüfen.
Token noch im Dashboard vorhanden? Falls gelöscht: neuen erstellen, in config.json eintragen.
Steht in der Config noch PASTE_LOCAL_TOKEN_HERE? Dann läuft der Watcher absichtlich im Dry-Run — kein Fehler, aber es kommt auch nichts bei Chatlix an.

"source_not_allowed" bei eigener Integration

Siehe Tabelle oben — source ist eine feste Allowlist, kein Freitext. Für eigene Server-Mods/Scripts generic-log oder generic-json als source verwenden, das eigentliche Spiel im game-Feld oder in watcher_id unterbringen.

Events kommen an, aber keine Cinematic feuert

Ist die Severity low? Low-Severity-Events (z.B. chat_message, player_join/player_leave) lösen absichtlich nie Cinematics oder Overlay-Alerts aus.
Lighting-Gerät verbunden? Cinematics ohne Licht laufen technisch, aber sichtbar ist davon wenig.
Existiert ein Mapping für (game, event_type)? Nicht jeder Event-Typ hat einen Default-Cinematic-Slug.
Cooldown der Event-Reaction aktiv? Unter Dashboard → Game Watcher → Reactions prüfen.
Eigene Automation statt Preset gewünscht? Im Automation-Editor Trigger-Typ game_watcher_event mit Filter auf event_type bauen.

Events kommen doppelt

Mehrere Watcher mit derselben watcher_id laufen gleichzeitig? Eindeutige IDs vergeben.
Der Server-Dedupe basiert auf sha256(user_id · watcher_id · event_type · occurred_at · actor · body[0..200]). Bei Custom-HTTP-Posts auf konsistente occurred_at- und Text-Felder achten, sonst greift der Dedupe nicht und du bekommst zwei Zeilen für dasselbe Ereignis.

Stats/Stream-Stats aktualisieren sich nicht oder sind leer

Retention-Limit deines Plans greift (siehe Stats-Seite) — Free-Plan sieht z.B. maximal 30 Tage zurück, egal welchen Range du wählst.
Zeigt die Seite "Noch keine Game-Watcher-Daten im gewählten Zeitraum"? Dann ist im gewählten Range/Range-Cutoff wirklich nichts angekommen — Setup nochmal mit doctor/test-event prüfen.
Filter im Stats-Tab: prüfe, ob du versehentlich einen Watcher oder eine Severity ausgefiltert hast.

Connect-Watcher startet nicht (Windows)

Connect installiert, Tray-Icon vorhanden?
Game-Watcher-Modul in Connect-Settings aktiviert?
Antivirus blockiert die Connect-Binary? Siehe Connect-Troubleshooting im Wiki.

"Game-Log nicht gefunden" (Standalone, Minecraft)

Auto-Detection scheitert bei Custom-Installationen — Pfad in paths.latestLog explizit setzen, z.B. C:/Users/DU/AppData/Roaming/.minecraft/logs/latest.log.
doctor --config config.json ausführen — zeigt exakt, welcher Pfad nicht lesbar ist.

Player-Namen sollen gefiltert werden

Beim Minecraft-Watcher playerName auf den gewünschten Spieler setzen — Events anderer Spieler im selben Log werden dann ignoriert.
Für einen echten Anonymisierungs-/Whitelist-Mechanismus über mehrere Watcher-Typen hinweg gibt es aktuell keine eingebaute Option — das war in der alten Doku so behauptet, existiert im Code aber nicht. Wer das braucht: eigenen generic-log-Regex bauen, der den Namen gar nicht erst in eine Capture-Group packt.