Troubleshooting

Start at System → Connection Status, or click the networking icon beside the clock. If a row is red, click Fix…. That opens the settings window for that row.

Use System Status for Twitch authorization. Use Logs and Diagnostics after you have a timestamp. Sanitize output per Security.

Bot is not in chat

Complete SETUP BOT Sign-In. Broadcaster is required. Sign in a bot account if you expected chat to use a bot name. Channel name must be the lowercase login. It is not the display name with capitals.

If !ping gets no reply, the bot process is down or it never joined. On Windows, read the console window. On Linux with the package, use journalctl -u grimbot.

Follows and subs never fire Event Alerts

Check EventSub. Open System Status. Click Re-subscribe EventSub after a fresh broadcaster Authorize.

On a single PC, transport is websocket. You do not need a public URL. If you set PUBLIC_BASE_URL for a tunnel, that URL must be accurate. Otherwise Twitch posts events to the wrong place.

Preview on an Event Alert tab tests the card. Event Emulator is not a card test.

Overlay is blank in OBS

Canvas size must match the Browser Source. The URL must be the one Overlay Browser copied. It must be reachable from the OBS PC.

If Control audio via OBS is off, clips are silent. The frame is not blank. A blank frame usually means the layout has no objects, or you are looking at a different overlay URL.

Refresh the Browser Source once after you add objects if the socket connected before the object existed.

Spotify commands fail

Confirm Premium, the app open, a track already playing, Market matching your country, and a Song Requests playlist selected. Authorize again if Spotify revoked the token.

TTS is silent

Speaker.bot must speak when you test inside Streamer.bot. Then test from GRiMbOS Streamer.bot settings. The agent window must be open. The token must match. Game TTS checkboxes are off on a fresh game install on purpose.

Handy does nothing

Use the Post-Processing hotkey. Do not use the transcribe hotkey. The prompt body must be ${output}. The URL must be http://127.0.0.1:28787/v1. The agent must run on the streaming PC, not on the server. Integration enabled must be ticked.

Discord Test Connection fails

Check the token, Message Content Intent, whether the bot is in the server, and whether Server ID is the guild. Do not paste a channel ID into Server ID.

Schedule will not save

The broadcaster token is missing schedule write scopes. Re-authorize broadcaster. Bot Timezone must be set. Otherwise "today" can be the wrong day.

GRiMbOS asks for login in a loop

SECRET_KEY may have changed. You may be mixing localhost and 127.0.0.1. A second GRiMbot may be bound to port 8000. Stop extra copies.

PC Agent lamp stays red

The token in the agent config must match STREAMERBOT_AGENT_TOKEN on the bot. The bot URL in the agent must reach GRiMbot. 127.0.0.1 in the agent is correct only when GRiMbot runs on the same PC. See PC Agent.

ATS or MSFS chat has no telemetry

For ATS, confirm scs-telemetry.dll is in the game plugins folder, the game is running, Units match the overlay, and the ATS Agent window is open if you chose Agent mode. See ATS.

For MSFS, confirm Little Navmap Run Web Server is on, usually port 8965, SimConnect is available if you need full weather, and the MSFS Agent is open in Agent mode. !speed is aircraft speed. Truck speed is !truckspeed. See MSFS.

AI Test fails or chat uses the fallback line

Open AI Settings, confirm Ai Enabled, and click Test on the Default AI Account. Check the API URL, key, and model for that AI Provider. Fallback AI Provider is not used automatically when Default fails. The Fallback message on Response Setup is the chat line when generation fails. See AI Integration.

StreamElements import fails

Paste a current JWT from the StreamElements dashboard. Click Test connection before Import / Refresh SE data. Channel id is optional. Leave it blank to use TWITCH_CHANNEL. This import does not replace EventSub follows or GRiMbot Lurk Points. See StreamElements.

Shop is empty or a buy is refused

Install Games Integration first, then the game zip that owns the item. Restart when GRiMbOS asks. DLC Manager must list that pack. !shop with no packs loaded has nothing to sell.

If chat reports stash full, the viewer is at stash capacity. Golden buds do not count against capacity. Green and purple buds do. A Mason Jar from Munchies raises capacity.

!games is a fixed starter list. It does not prove which DLC is installed. Use DLC Manager.

Database

Packaged installs use data/grimbot.db. If you delete that file you lose history and you will run SETUP BOT again. Back it up when the install is working.