Troubleshooting

Common issues and their solutions, organized by symptom.

Pipeline Server Not Connecting

Symptom: Dashboard shows "Pipeline server unreachable"

1. Verify the server is running: curl http://localhost:8750/health
2. Check PIPELINE_SERVER_TOKEN matches in both .env.local and pipeline-server/.env
3. Check PIPELINE_SERVER_PORT matches (default: 8750)
4. If using Tailscale, verify the funnel is active: tailscale funnel status

Cannot Log In (Auth Loop)

Symptom: Redirected back to the login page after GitHub auth

1. Verify NEXTAUTH_SECRET is set (generate with openssl rand -base64 32)
2. Verify NEXTAUTH_URL matches your actual URL (http://localhost:3000 for local)
3. Verify the GitHub OAuth callback URL matches exactly: http://localhost:3000/api/auth/callback/github
4. Clear browser cookies and try again
5. On Vercel: do NOT set NEXTAUTH_URL — Vercel handles this automatically

Pipelines Start But Produce No Output

Symptom: Pipeline jobs start but nothing appears

1. Verify ANTHROPIC_API_KEY is set in pipeline-server/.env
2. Verify Claude Code CLI is installed: claude --version
3. Check pipeline server logs for errors
4. Verify the knowledge vault path is correct: KNOWLEDGE_DIR in pipeline-server/.env

Notion API Errors

Symptom: Pipelines fail with "Could not find database" or 401 errors

1. Verify NOTION_API_KEY is correct
2. Verify both databases are shared with your integration (Section 4.4 of the setup guide)
3. Verify database IDs are correct (32 hex chars, no dashes)

"KNOWLEDGE_DIR not set" on Startup

Symptom: Pipeline server refuses to boot

Ensure all required env vars are set in pipeline-server/.env:

KNOWLEDGE_DIR=/Users/yourname/agency-workspace/knowledge
HQ_URL=http://localhost:3000
PIPELINE_SERVER_TOKEN=your-token-here
ANTHROPIC_API_KEY=sk-ant-...

Crons Not Firing

Symptom: Scheduled jobs do not run

1. Check the job is enabled: true in cron-config.json
2. Restart the pipeline server after config changes
3. Check if current time falls within quiet hours (quiet_start / quiet_end)
4. Verify via: curl http://localhost:8750/crons/health -H "Authorization: Bearer TOKEN"

Database Errors (SQLite)

Symptom: Dashboard shows errors reading/writing data

1. Verify the ./data/ directory exists and is writable
2. Run bun run migrate to apply pending schema changes
3. If the database file is corrupted, delete ./data/gridwork-hq.db and restart — it will be recreated

Build Failures (TypeScript)

Symptom: npm run build fails with type errors

npx tsc --noEmit   # See exact errors
npm run lint        # Check for lint issues

Common causes: missing environment variable types, stale imports after brand config changes.

Telegram Notifications Not Sending

Symptom: Cron jobs complete but no Telegram messages

1. Verify TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in pipeline-server/.env
2. Get your chat ID: message @userinfobot on Telegram
3. Test manually:

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -d "chat_id=<ID>&text=test"

Out of Memory

Symptom: Node.js crashes with heap allocation errors during pipeline runs

# Increase Node.js heap size
export NODE_OPTIONS="--max-old-space-size=4096"
bun run dev

Or add to your LaunchAgent/systemd config.

502 Bad Gateway (VPS)

Symptom: Nginx returns 502

1. Check the app is running: pm2 status or systemctl status agency-pipeline
2. Verify the port matches Nginx config (3000 for dashboard, 8750 for pipeline server)
3. Check Nginx logs: sudo tail -f /var/log/nginx/error.log

SSL Certificate Renewal Fails (VPS)

# Test renewal
sudo certbot renew --dry-run

# If it fails, check Nginx and port 80
sudo ufw status
sudo systemctl status nginx

Slow Dashboard Performance (VPS)

1. Ensure you ran npm run build (not just npm run dev in production)
2. Check RAM — upgrade to 4 GB+ if needed
3. Add swap space if running low on memory:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab