Troubleshooting

Dashboard does not load on port 8080

Likely cause: the container is not running or the port was never published.

docker ps --filter name=golemcore-bot
docker logs --tail=50 golemcore-bot

Fix: if the container is stopped, restart it with -p 8080:8080. If the container is running but the dashboard still does not load, check that Tomcat started cleanly in the logs — a missing volume or corrupted preferences file will abort startup.

Settings disappear after every restart

Likely cause: the workspace volume is not mounted, so preferences are written to the ephemeral container filesystem and discarded on restart.

docker inspect golemcore-bot --format '{{ range .Mounts }}{{ .Destination }} {{ end }}'

Fix: restart the container with -v golemcore-bot-data:/app/workspace. The Configuration page has the full command.

Initial admin password not in the logs

Likely cause: the container has already stored an admin record on the volume, so no bootstrap password is generated on subsequent starts.

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

Fix: reset the password through Settings → Security. If you are locked out entirely, set BOT_DASHBOARD_ADMIN_PASSWORD at container start — the runtime accepts it as an override at boot.

Rate limit exceeded from the provider

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

docker logs golemcore-bot | grep -E "rate_?limit|429"

Fix: raise the provider tier, set a lower concurrency in preferences/runtime-config.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, or switch the tier to a model with a larger context window for the duration of the investigation.

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 -E "mcp|handshake|timeout"

Fix: raise startup_timeoutin the skill's MCP section (60s is a safe default for first runs), or preinstall the MCP server package into the image.

Tools from the MCP server never register

Likely cause: the handshake failed silently, or the skill was deactivated before the handshake completed.

Check: run /skills list and confirm the skill is Active. Then tail docker logs for a line about the MCP server entering the Ready state.

Fix: reactivate the skill after the fix; tools only register while the skill is Active.

Webhook delivery stays in PENDING

Likely cause: the target hook cannot activate its skill, or the runtime is under load.

docker logs golemcore-bot | grep -E "webhook|hook|delivery"

Fix: inspect the Sessions page for the stuck delivery and look at which stage it is waiting on. Most often it is skill activation — see the MCP and Skills entries above.

Telegram bot does not reply

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

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

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

Browser plugin crashes on page load

Likely cause: missing Chromium shared memory flags. Chromium silently crashes inside Docker when/dev/shm is the default 64 MiB.

Check: run docker inspect golemcore-bot and look forShmSize.

Fix: restart the container with --shm-size=256m --cap-add=SYS_ADMIN. Both flags are required; neither alone is enough.

Traces directory fills the disk

Likely cause: default retention is longer than your workload generates trace volume for.

docker exec golemcore-bot du -sh /app/workspace/traces

Fix: lower traces.retentionDays in preferences/runtime-config.json, or prune the directory manually after stopping the container.