Common issues and their solutions when running Z.E.N..

Bot Not Responding

Check if the application is running:

If running locally:

# Check the server process
curl http://localhost:3090/health
# Expected: {"status":"ok"}

If running via Docker:

docker compose ps
# Should show 'app' with state 'Up'

Check application logs:

Local:

# Server logs are printed to stdout when running `bun run dev`

Docker:

docker compose logs -f app

Verify bot token:

# In your .env file
cat .env | grep TELEGRAM_BOT_TOKEN

Test with health check:

curl http://localhost:3090/health
# Expected: {"status":"ok"}

Database Connection Errors

Check database health:

curl http://localhost:3090/health/db
# Expected: {"status":"ok","database":"connected"}

For SQLite (default):

SQLite requires no setup. The database is created automatically at ~/.zen/zen.db. If you see errors, check that the ~/.zen/ directory exists and is writable.

For remote PostgreSQL:

# Verify DATABASE_URL
echo $DATABASE_URL

# Test connection directly
psql $DATABASE_URL -c "SELECT 1"

Verify tables exist (PostgreSQL):

psql $DATABASE_URL -c "\dt"

# Should show: remote_agent_codebases, remote_agent_conversations, remote_agent_sessions,
# remote_agent_isolation_environments, remote_agent_workflow_runs, remote_agent_workflow_events,
# remote_agent_messages

Clone Command Fails

Verify GitHub token:

cat .env | grep GH_TOKEN
# Should have both GH_TOKEN and GITHUB_TOKEN set

Test token validity:

# Test GitHub API access
curl -H "Authorization: token $GH_TOKEN" https://api.github.com/user

Check workspace permissions:

The workspace directory is ~/.zen/workspaces/ by default (or /.zen/workspaces/ in Docker). Make sure it exists and is writable.

Try manual clone:

git clone https://github.com/user/repo ~/.zen/workspaces/test-repo

GitHub Webhook Not Triggering

Verify webhook delivery:

1. Go to your webhook settings in GitHub
2. Click on the webhook
3. Check "Recent Deliveries" tab
4. Look for successful deliveries (green checkmark)

Check webhook secret:

cat .env | grep WEBHOOK_SECRET
# Must match exactly what you entered in GitHub

Verify ngrok is running (local dev):

# Check ngrok status
curl http://localhost:4040/api/tunnels
# Or visit http://localhost:4040 in browser

Check application logs for webhook processing:

Local:

# Look for GitHub-related log lines in server output

Docker:

docker compose logs -f app | grep GitHub

Port Conflicts

Check if port 3090 is already in use:

macOS/Linux:

lsof -i :3090

Windows:

netstat -ano | findstr :3090

You can override the port with the PORT environment variable:

PORT=4000 bun run dev

When running in a git worktree, Z.E.N. automatically allocates a unique port (3190-4089 range) so you don't need to worry about conflicts with the main instance.

Stale Processes (Windows)

Symptom: The Web UI shows a spinning indicator with no response, and the terminal shows no activity; even though you've started bun run dev.

Cause: A previous bun or node process is still holding the port. This is common on Windows when the terminal is closed without stopping the server.

Diagnose:

netstat -ano | findstr :3090

Note the PID in the last column, then verify which process it is:

tasklist | findstr 12345

(Replace 12345 with the actual PID.)

Fix; kill by PID (preferred):

taskkill /F /PID 12345

If multiple stale processes are present:

taskkill /F /IM bun.exe
taskkill /F /IM node.exe

WARNING

Do not kill claude.exe processes; those are active Claude Code sessions.

See also: Windows Setup for more Windows-specific guidance.

E2E Testing / agent-browser

agent-browser: command not found:

agent-browser is an optional external dependency; see the E2E Testing Guide for installation.

npm install -g agent-browser
agent-browser install

agent-browser daemon fails to start (Windows):

agent-browser has a known Windows bug. Use WSL as a workaround; see E2E Testing on WSL.

agent-browser daemon fails to start (macOS/Linux):

Kill stale daemons and retry:

pkill -f daemon.js
agent-browser open http://localhost:3090

Docker

These issues are specific to running Z.E.N. inside Docker containers.

Container Won't Start

Check logs for specific errors:

docker compose logs app

Verify environment variables:

# Check if .env is properly formatted
docker compose config

Rebuild without cache:

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

If using the with-db profile, add --profile with-db to the above commands.

Docker Database Issues

For local PostgreSQL (with-db profile):

# Check if postgres container is running
docker compose --profile with-db ps postgres

# Check postgres logs
docker compose logs -f postgres

# Test direct connection
docker compose exec postgres psql -U postgres -c "SELECT 1"

Verify tables exist (Docker PostgreSQL):

docker compose exec postgres psql -U postgres -d zen -c "\dt"

# Should show: remote_agent_codebases, remote_agent_conversations, remote_agent_sessions,
# remote_agent_isolation_environments, remote_agent_workflow_runs, remote_agent_workflow_events,
# remote_agent_messages

Docker Clone Issues

Check workspace permissions inside the container:

docker compose exec app ls -la /.zen/workspaces

Try manual clone inside the container:

docker compose exec app git clone https://github.com/user/repo /.zen/workspaces/test-repo

Running Z.E.N. From Inside Claude Code

The CLI deletes the parent session's CLAUDECODE / CLAUDE_CODE_* markers from process.env at entry, so the embedded Claude Agent SDK's nested-session guard never sees them. You don't need to set anything; running zen workflow run ... from inside a Claude Code session just works.

If a workflow hangs: every Claude subprocess is wrapped with a first-event timeout (60s default) that produces a structured diagnostic log at claude.first_event_timeout if no output arrives. Read that log entry for the parent env keys, model, UID, and TTY state at the time of the hang.

Adjust the timeout: if your environment is slow:

ZEN_CLAUDE_FIRST_EVENT_TIMEOUT_MS=120000 zen workflow run ...