Skip to main content

Common Errors

Installation Issues​

DASHBOARD_SECRET must be at least 16 characters​

Symptom: agent-core fails to start immediately.

Fix:

# In .env
DASHBOARD_SECRET=my_very_secure_secret_password_here

agent-core keeps restarting​

Check logs:

docker compose logs agent-core --tail=50

Common causes:

  1. Missing required env vars (POSTGRES_PASSWORD, DASHBOARD_SECRET)
  2. PostgreSQL not ready (check docker compose ps — postgres must be healthy)
  3. Python import error (rebuild container)

Fix for import error:

docker compose build agent-core --no-cache
docker compose up -d agent-core

Bot not responding on Telegram​

Cause 1: Wrong TELEGRAM_ALLOWED_USERS

# Get your real Telegram user ID
curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates"
# Look for "from":{"id": YOUR_ID_HERE}

Cause 2: Invalid bot token

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"
# Should return bot info, not error

Cause 3: Telegram bridge not running

docker compose logs agent-telegram --tail=20
docker compose restart agent-telegram

SSL certificate errors on agentwasp.com​

Check cert files exist:

ls /etc/letsencrypt/live/agentwasp.com/
# Should show: cert.pem chain.pem fullchain.pem privkey.pem

Check nginx config:

docker exec agent-nginx nginx -t

Renew certificate:

certbot renew --nginx
docker compose restart agent-nginx

Runtime Errors​

context_length_exceeded / too many tokens​

Cause: Conversation history too long for model context window.

How WASP handles it: Automatic progressive truncation:

  • Full context → 4 exchanges → 2 exchanges → 1 exchange
  • System prompt always preserved
  • Logged as model_manager.overflow_recovered

If it persists:

# Switch to a model with larger context
/model claude-3-5-sonnet     # 200k context
/model gemini-1.5-pro        # 1M context

Skill execution timeout​

Symptom: Skills return timeout errors.

Cause: Shell/Python/Browser skill exceeded 60-120s timeout.

Fix: For long-running tasks, split into shorter steps or use background goals.

Goals stuck in ACTIVE status​

Cause: Goal paused and not auto-resuming, or hit budget limit.

Check goal state:

docker exec agent-redis redis-cli HGETALL goals

Force delete stuck goal:

docker exec agent-redis redis-cli HDEL goals <goal-id>

Restart goal engine:

docker compose restart agent-core

Redis stream backlog growing (XLEN events:incoming > 5000)​

Cause: agent-core can't process messages fast enough.

Check:

docker exec agent-redis redis-cli XLEN events:incoming
docker compose logs agent-core --since=5m | grep error

Fix: Usually a crashed agent-core. Restart:

docker compose restart agent-core
# If needed, trim the stream:
docker exec agent-redis redis-cli XTRIM events:incoming MAXLEN 1000

Browser skill fails / Chromium crash​

Symptom: Browser skill returns "Session error" or "Chromium crash"

Fix 1: Ensure browser-sessions directory has correct permissions:

chmod 777 /home/agent/data/browser-sessions
docker compose restart agent-core

Fix 2: Check shm_size:

# docker-compose.yml
agent-core:
  shm_size: '2gb'  # Must be present

Fix 3: Kill orphaned Chromium processes:

docker exec agent-core pkill -f chromium || true

Gmail skill not working​

Check credentials:

docker exec agent-redis redis-cli HGETALL gmail:credentials

Re-seed credentials:

# Set via environment variables and restart
GMAIL_ADDRESS=your@gmail.com
GMAIL_APP_PASSWORD=your-app-password
docker compose restart agent-core

Verify App Password: Must be a Gmail App Password (16 chars), not your main Gmail password.

No AI providers configured​

Symptom: Agent responds "No model configured"

Fix:

/api set openai sk-your-key-here

Or set in .env and restart:

OPENAI_API_KEY=sk-your-key docker compose up -d agent-core

plan_critic_init_failed​

Cause: Plan critic failed to initialize (usually import error)

Check logs:

docker compose logs agent-core | grep plan_critic

Fix: Usually a rebuild solves it:

docker compose build agent-core && docker compose up -d agent-core

Behavioral rules not loading​

Check table:

docker exec agent-postgres psql -U agent -d agent -c \
  "SELECT COUNT(*) FROM behavioral_rules WHERE active=true;"

If empty: No corrections processed yet — this is normal initially.

Data Issues​

Memory not persisting after restart​

Check volumes:

ls /home/agent/data/postgres/
ls /home/agent/data/memory/

If empty, volumes weren't created correctly. Check docker-compose.yml volume bind mounts.

Knowledge Graph not populating​

Check extraction is running:

docker compose logs agent-core | grep "kg_extract\|knowledge_graph"

Manually trigger extraction:

# Send a message with entities to the agent
# "Tell me about BTC, ETH, and my server at 76.13.232.149"

Getting Help​

  1. Check logs: docker compose logs agent-core --tail=100
  2. Check health: curl http://localhost:8080/health
  3. Check Redis: docker exec agent-redis redis-cli INFO
  4. Check Postgres: docker exec agent-postgres psql -U agent -d agent -c "SELECT NOW();"