Troubleshooting

pgvector Extension Requires Superuser

Problem: CREATE EXTENSION vector fails with “permission denied to create extension”.

Cause: The assistant database user is not a superuser. PostgreSQL extensions must be created by a superuser.

Solution: Install the extension using the database superuser:

# Find your superuser name (check POSTGRES_USER in docker-services/.env)
docker exec <db-container> psql -U <superuser> -d assistant \
  -c "CREATE EXTENSION IF NOT EXISTS vector;"

After that, the non-superuser assistant role can use the extension normally. The migration code handles this gracefully — if the extension cannot be created, it logs a warning and continues without vector search.

Migration Error: “Can’t find meta/_journal.json”

Problem: Drizzle ORM migrations fail because the metadata journal file is missing.

Cause: The migration SQL file exists but the Drizzle metadata directory (src/db/migrations/meta/) was not created.

Solution: Ensure the meta directory and journal exist:

mkdir -p src/db/migrations/meta

Create src/db/migrations/meta/_journal.json:

{
  "version": "7",
  "dialect": "postgresql",
  "entries": [
    {
      "idx": 0,
      "version": "7",
      "when": 1708000000000,
      "tag": "0000_initial",
      "breakpoints": true
    }
  ]
}

Collation Version Mismatch Warning

Problem: PostgreSQL warns about collation version mismatch on every query.

Cause: The database was created with a different OS/glibc version than the current container. This is harmless.

Solution (optional): Run inside the database container:

ALTER DATABASE assistant REFRESH COLLATION VERSION;

Model Registry Duplicate Key on Restart

Problem: Server crashes with Key (name)=(cli/codex-cli) already exists on restart.

Cause: This was a bug where disabled models were not found during the existence check, causing duplicate INSERT attempts.

Status: Fixed. The model registry now checks existence regardless of isEnabled status.

Database Connection Failed

Problem: Server fails to start with PostgreSQL connection error.

Solution:

# Check PostgreSQL is running
cd ~/docker-services && docker compose ps db

# Start it if stopped
docker compose up -d db

# Verify connection
docker exec <db-container> psql -U <user> -d assistant -c "SELECT 1;"

# Check DATABASE_URL in .env matches your docker-services credentials

Redis Connection Failed

Problem: Server fails to start with Redis connection error.

Solution:

# Check Redis is running
cd ~/docker-services && docker compose ps redis

# Start it if stopped
docker compose up -d redis

# Test connection
docker exec <redis-container> redis-cli ping

LiteLLM Not Running

Problem: Model health checks fail, no LLM responses.

Solution:

cd ~/docker-services
docker compose up -d litellm

# Check logs
docker compose logs litellm

# Verify it's reachable
curl http://localhost:4000/health

Port Conflicts

Problem: “Address already in use” on startup.

Solution: Check what is using the port and either stop it or change the port in .env:

# Check what's using a port
lsof -i :3005   # Backend
lsof -i :3007   # Web UI

# Or change ports in .env
API_PORT=3008
WEB_PORT=3009

Browser Skill: Playwright Not Installed

Problem: Browser skill fails with “Executable doesn’t exist”.

Solution:

bunx playwright install chromium

This downloads the Chromium browser binary that Playwright uses for browser automation and web scraping.