Troubleshooting

Run mobrule doctor first

Before chasing any symptom below, run this from a terminal on the streaming PC:

mobrule doctor

It’s a quick, read-only health check of your local bridge: is the Local API token where it should be, is the bridge actually reachable, are you paired, is your CLI talking to the same version as the bridge, is your Pack’s pack.toml still what the bridge loaded, and is the game adapter connected. Each line is ok, WARN, or FAIL, and a FAIL line comes with a one-line hint for what to try next:

ok   local_token: found at ~/.config/mobrule/local_token
ok   bridge_reachable: bridge responded
ok   paired: paired — active pack tv.mobrule.pack-doom
ok   twitch_auth: ok
ok   session_liveness: last seen 2100ms ago
ok   version_match: CLI and bridge both 0.4.0
ok   active_pack: tv.mobrule.pack-doom v1.2.0 (sha256:...)
ok   pack_drift: pack.toml matches the running manifest
FAIL adapter_handshake: manifest_hash_mismatch — adapter pack_id=tv.mobrule.pack-doom hash=...; bridge pack_id=tv.mobrule.pack-doom hash=...
     hint: rebake: scripts/manifest-hash.sh --bake in the pack repo, rebuild adapter

It never changes anything on the bridge — it’s safe to run any time, as often as you like. Add --json if you want the same checks as a script-friendly array instead of the human-readable lines above.

If a check comes back skip, that’s not a problem on its own — it usually means the bridge is too old to answer that particular check (update it), or the check legitimately doesn’t apply yet (no pack active, no adapter has ever connected).

Windows SmartScreen blocks the installer

Expected for the current unsigned build. See Install. Click More info → Run anyway, and only download from the official release page.

Pairing fails or the bridge shows “not paired”

• Complete the whole flow in one go: the claim code handed back by the browser is single-use and expires in 60 seconds. If you waited, start pairing again from the Dashboard.
• If the bridge was previously paired and stopped working after a platform reset or reinstall, simply re-pair from the Dashboard. Re-pairing is safe: it replaces the cloud credential and nothing else.

The game adapter won’t connect

• Launch through the Dashboard. The Launch game button injects the adapter’s connection token; a game started by hand has no token and is rejected (invalid_token).
• manifest_hash mismatch. The Pack on disk changed after the adapter computed its hash. Restart the adapter (relaunch the game) so it picks up the current hash.
• Check the Launcher panel paths still point at the right executable/files (they are per-machine and need re-picking if you moved or re-extracted the Pack).

Rewards aren’t redeemable

Symptom: Rewards show as unavailable on your channel and viewers can’t redeem them.

Check the bridge first. This is the most common cause. The platform auto-disables your Rewards whenever it stops hearing from the bridge. The bridge heartbeats every 60 seconds; if no heartbeat lands within about 150 seconds (2.5 heartbeat periods), the platform marks the bridge dead and forces every Reward off. The fix is to get the bridge reconnected: confirm the tray icon is present, check the streaming PC’s network, and watch the Dashboard. Rewards re-enable on their own once heartbeats resume.

If the bridge is live, two switches must both allow a Reward:

• Enabled: your manual on/off per Reward in the Dashboard.
• Pause: the platform auto-pauses a Reward while the game is in a context where its effect can’t apply (if the Pack uses this feature). The pause lifts on its own when the game context changes. It never overrides your enabled switch, and the enabled switch never overrides it.

A viewer was refunded and the effect never fired

Symptom: A redemption shows as refunded in the audit panel and the effect didn’t run.

Two causes are issued at ingestion, the moment the redemption reaches the platform:

• reward_disabled: the Reward was off when the redemption arrived. The bridge-liveness gate above also turns Rewards off, so a dead bridge produces these refunds.
• reward_on_cooldown: the Reward was still inside its cooldown window. Raise the cooldown if viewers hit it too often.

Pause works differently. A paused Reward is paused on Twitch, so the redemption never reaches the platform and no refund row is created. If you expected a refund and see none, check whether the Reward was paused.

The overlay is empty in OBS

• Confirm a Pack is active in the Dashboard and that the bridge is running (tray icon present). The overlay renders an empty stage until a Pack is active.
• Use the exact overlay URL from the Dashboard’s Overlay tab.
• An overlay only shows data while the game adapter is connected and publishing; launch the game and check the audit panel shows activity.
• If you just changed Packs, the overlay reloads itself within a few seconds; refresh the browser source if it doesn’t.

Quitting the bridge

Quit the bridge from the system tray (or the Dashboard), not by killing the process. Force-killing the daemon can leave its network ports wedged until a reboot. Close the game before stopping the bridge if the bridge launched it.

Where to look for detail

The Dashboard’s audit panel is the first stop: every redemption’s lifecycle (pending → dispatched → applied → done, or failed at any step) is visible there, including failures the game reported and the terminal refunded state for refunds the platform issued.