Troubleshooting

Rate limit exceeded from the provider

Likely cause: request burst or shared key across multiple bots.

docker logs golemcore-bot | grep -Ei "rate.?limit|429"

Fix:raise your plan's limit with the provider, lower llmRequestsPerMinute in preferences/rate-limit.json, or route the affected tier to a different provider in the model router.

Model router falls back to balanced on unknown tier

Likely cause: a skill references a tier name that is not configured in preferences/model-router.json.

docker exec golemcore-bot cat /app/workspace/preferences/model-router.json

Fix: either add the missing tier mapping, or change the skill to use a tier you actually have configured. balanced must always be present as the ultimate fallback.

Context length exceeded on a long session

Likely cause:auto-compaction cannot fit the session into the model's context window.

Check: look at the failing turn in Sessions. If auto-compaction ran but still overflowed, the message shows it explicitly.

Fix: start a new session (cleanest), let dynamic escalation pick a larger model on retry, or edit the affected tier in preferences/model-router.json to point at a model with a wider context window before resuming.

Skill does not appear in /skills list

Likely cause: the SKILL.md file is missing or has invalid YAML frontmatter.

docker exec golemcore-bot ls /app/workspace/skills/
docker exec golemcore-bot head -n 10 /app/workspace/skills/<name>/SKILL.md

Fix:confirm the directory name matches the skill's name field and that the frontmatter block is delimited by --- on its own line at both ends.

MCP handshake timeout on first activation

Likely cause: the MCP server takes longer than startup_timeout to launch — common on first npx use because the package is still downloading.

docker logs golemcore-bot | grep -Ei "mcp|handshake|timeout"

Fix: raise startup_timeoutin the skill's mcp: block (60s is a safe default for first runs), or pre-download the MCP server package into the image.

Tools from the MCP server never register

Likely cause: the handshake never completed, or the skill was deactivated before the handshake finished.

Check: tail docker logs for a line about the initialize and tools/list handshake completing for your skill. The bot only exposes MCP tools after both steps finish.

Fix: trigger the skill again in a fresh message. If the handshake still does not complete, raise startup_timeoutand inspect the MCP server's own stderr for a launch error.

Webhook returns status: "error"

Likely cause: bad auth, unknown hook name, or an internal handler failure. The webhook endpoints are synchronous at the HTTP layer — they return accepted or error immediately, not a queued status.

docker logs golemcore-bot | grep -Ei "webhook|hook"

Fix: if errorMessage in the response mentions auth, verify the bearer token or HMAC signature matches preferences/webhooks.json. If it mentions the hook name, confirm the custom hook is defined. For everything else, inspect the Sessions page using the chatId from the response body.

Telegram bot does not reply

Likely cause: token misconfigured, user not in the allow-list, or Telegram disabled in preferences.

docker exec golemcore-bot cat /app/workspace/preferences/telegram.json

Fix: verify the token with @BotFather, add your user ID to allowedUsers, and confirm enabled is true.

Browser plugin crashes on page load

Likely cause: missing Chromium shared memory and sandbox flags. Chromium silently crashes inside Docker when /dev/shm is the default 64 MiB, and its user-namespace sandbox needs an extra capability.

Check: run docker inspect golemcore-bot and look for ShmSize and CapAdd.

Fix: restart the container with --shm-size=256m --cap-add=SYS_ADMIN. Both flags are the officially documented Playwright-in-Docker configuration; neither alone is enough.

Traces fill the disk

Likely cause: the per-session trace budget is larger than your disk can absorb for the number of sessions you run.

docker exec golemcore-bot du -sh /app/workspace/traces
docker exec golemcore-bot cat /app/workspace/preferences/tracing.json

Fix: lower sessionTraceBudgetMb (default 128) and maxTracesPerSession (default 100) in preferences/tracing.json. Tracing is size- and count-capped, not time-capped — you can also prune the directory manually with the container stopped.