Troubleshooting

Solutions to the most common issues encountered when running Gumm.

Quick diagnostics

Start here when something is wrong:

# Check container status
docker compose ps

# View live logs
docker compose logs -f gumm

# Check Redis
docker compose logs redis

# Test the health endpoint
curl http://localhost:3000/api/health

Installation issues

The container won’t start

Check the logs:

docker compose logs gumm

Common causes:

I can’t reach the dashboard

1. Check the container is running: docker compose ps
2. Check the port binding: docker compose port gumm 3000
3. If VPN_BIND_IP is set, you must be on the VPN to access it
4. Try curl http://localhost:3000/api/health from the server itself

Setup Wizard doesn’t appear

If you visit http://server:3000 and are redirected to /login instead of /setup, the setup was already completed (or marked as completed in the database).

To reset:

# Connect to the database
docker compose exec gumm bun run db:studio
# Or directly via SQLite:
docker compose exec gumm sh -c "sqlite3 /app/.data/hub/d1/default.db \"DELETE FROM brainConfig WHERE key='setup.completed';\""

Then refresh the page — the wizard will appear again.

Login issues

”Invalid password”

• Double-check the password matches GUMM_ADMIN_PASSWORD in your .env
• If you changed the password in the Brain dashboard after setup, use the new password (the env var is only used during setup)
• Password is case-sensitive

”Setup not complete”

The setup wizard was not finished. Navigate to http://server:3000/setup to complete it.

Locked out (forgot password)

If you can access the container, reset the password directly:

# Generate a bcrypt hash of your new password
docker compose exec gumm node -e "
const { hashSync } = require('bcryptjs');
console.log(hashSync('new-password', 10));
"

# Update the hash in the database
docker compose exec gumm sh -c "sqlite3 /app/.data/hub/d1/default.db \"UPDATE brainConfig SET value='PASTE_HASH_HERE' WHERE key='admin.passwordHash';\""

Chat / LLM issues

”OpenRouter API key is not configured”

Go to Brain → Configuration and ensure openrouter.apiKey is set. Or re-run the setup at /setup.

The AI isn’t responding

1. Check your OpenRouter key is valid and has credits at openrouter.ai/activity
2. Check docker compose logs gumm for LLM errors
3. Try a simpler message to rule out quota limits

Rate limit errors (HTTP 429)

You’ve sent too many messages too quickly. Wait 60 seconds and try again. Limits: 30 messages/minute, 5 messages/5 seconds.

The AI keeps forgetting context

Gumm maintains context within a conversation (all messages in the current thread). If context seems limited, you may be hitting the model’s context window limit. Start a new conversation or summarize key info at the start.

Module issues

A module shows a red error status

1. Click the module to see the error details
2. Common causes:
   • manifest.json has invalid JSON or missing required fields
   • index.ts does not export tools or handler
   • A dependency module is missing or disabled
   • TypeScript syntax error in the module code
3. Fix the issue in the module files — the registry will attempt to reload automatically

A module was installed but doesn’t appear in the list

Check docker compose logs gumm for validation errors. The module may have been rejected due to a manifest schema violation.

Hot-reload isn’t working

Module hot-reload requires the modules/user/ directory to be correctly mounted as a Docker volume. Check docker compose.yml:

volumes:
  - ./modules/user:/app/modules/user

Ensure the path ./modules/user exists on your host.

Telegram issues

Bot doesn’t respond to messages

1. Check that your Telegram numeric user ID is in the allowedChatIds whitelist (Brain → Telegram settings)
2. Check docker compose logs gumm for Telegram errors
3. Try sending /start to your bot

Webhook mode: messages not arriving

1. Ensure the webhook URL is HTTPS and publicly reachable
2. Check that Telegram can reach your server: curl https://your-domain/api/telegram/webhook
3. Switch to polling mode by removing the webhook URL from the Telegram settings

”Unauthorized” error in logs

Your bot token is invalid or expired. Regenerate it via BotFather (/revoke and then /token), then update it in the Brain dashboard.

VPN / Networking issues

CLI can’t connect to the brain

1. Run gumm status — check if the URL and credentials are correct
2. Verify both devices are on the same Tailscale/NetBird network: tailscale status or netbird status
3. Try ping <brain-VPN-IP> to verify basic connectivity
4. Check that gumm is accessible from the VPN IP: curl http://VPN_IP:3000/api/health

Container fails to start after setting VPN_BIND_IP

The VPN may not have connected before Docker allocated the port. Check logs:

docker compose logs gumm | grep -i "bind\|address\|vpn"

Try removing VPN_BIND_IP temporarily to confirm the container starts, then add it back once the VPN is stable.

Tailscale auth key rejected

Auth keys expire. Generate a new reusable key in the Tailscale admin console, update it in Settings → VPN Networking, and click Reconnect.

Database issues

Data disappeared after a restart

The SQLite database lives in the gumm-data Docker volume. If you used docker compose down -v, all volumes (including data) were deleted. The -v flag is destructive.

To back up your data:

docker run --rm -v gumm-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/gumm-backup-$(date +%Y%m%d).tar.gz /data

“Database is locked”

Restart the container:

docker compose restart gumm

If it persists, there may be a migration issue. Check logs for details.

Performance issues

Slow responses

1. Check the LLM model — larger models (e.g. GPT-4) are slower than smaller ones (e.g. mistral-small)
2. Reduce the number of active modules to limit the tool list injected per request
3. Check OpenRouter latency at status.openrouter.ai

High memory usage

If the container uses a lot of memory, check for stuck processes:

docker stats gumm

Redis should not use significant memory in normal use. If it does:

docker compose exec redis redis-cli info memory

Getting more help

1. Check docker compose logs gumm — most errors are visible in the logs
2. Check the GitHub Issues for known problems
3. Open a new issue with the relevant log output attached