Troubleshooting

Installation Issues

Bun Not Found

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Reload your shell
source ~/.bashrc  # or ~/.zshrc

Dependencies Won't Install

# Clear cache and reinstall
rm -rf node_modules bun.lock
bun install

Turborepo Cache Issues

# Clear Turborepo cache
rm -rf .turbo
bun run build

Database Issues

Database Locked

SQLite can only handle one write at a time. If you see "database is locked":

# Stop all Sesame processes
pkill -f sesame

# Restart the server
bun run dev

Reset Database

rm ./data/sesame.db
bun run dev  # Migrations run automatically

Migration Errors

If migrations fail:

# Check for schema issues
bun run db:push

# Or regenerate migrations
bun run db:generate
bun run db:migrate

Authentication Issues

Basic Auth Not Working

1. Check that AUTH_PASSWORD is set in your environment
2. Restart the server after changing the password
3. Clear browser cache (browsers cache Basic Auth credentials)
4. Check server logs for authentication errors

Agent Issues

Agent Not Starting

1. Verify the agent CLI is installed:

    claude --version  # For Claude Code
    codex --version   # For Codex
    gh copilot --version  # For Copilot
    gemini --version  # For Gemini
    amp --version     # For Amp

2. Check API keys are configured (Settings → API Keys)

3. Review session logs for specific errors

"Authentication Failed" Error

• For API keys: verify the key is valid and has sufficient credits
• For subscriptions: check Agent Credentials are configured
• Try removing and re-adding credentials

Agent Hangs or Times Out

Check if the agent is waiting for input:

# Check if agent process is running
ps aux | grep -E "claude|codex|gemini|amp"

Output Not Streaming

1. Check browser console for SSE connection errors
2. Verify the session status is "processing"
3. Try refreshing the page

GitHub Issues

"Invalid GitHub PAT" Error

1. Verify the token format:
   • Classic tokens start with ghp_
   • Fine-grained tokens start with github_pat_
2. Check the token hasn't expired
3. Verify required permissions (Contents, Pull Requests, Metadata)

Can't See Repositories

1. Check the PAT has access to the repository
2. For organization repos, ensure the org allows PAT access
3. For fine-grained tokens, verify the repo is in scope

Push Fails

1. Check the PAT has write access (Contents: Read and Write)
2. Verify branch protection rules allow pushes
3. Check if the repo requires signed commits

Docker Issues

Container Won't Start

# Check logs
docker compose logs sesame

# Common issues:
# - Missing environment variables
# - Port already in use
# - Insufficient memory

Permission Denied

# Fix volume permissions (container runs as 'bun' user, UID 1000)
docker compose exec sesame chown -R bun:bun /app/data /app/sandboxes

Out of Memory

Increase container memory limits:

services:
  sesame:
    deploy:
      resources:
        limits:
          memory: 4G

Health Check Failing

Check if the server is responding:

# From inside the container
docker compose exec sesame curl http://localhost:13531/api/health

# From the host
curl http://localhost:13531/api/health

Configuration Issues

Config Not Loading

1. Check file exists: config.json, config.yaml, etc.
2. Validate JSON/YAML syntax:

   cat config.json | jq .  # Validate JSON

3. Check admin UI at /admin/settings for current values

Environment Variable Not Working

1. Environment variables require a server restart
2. Check for typos in variable names
3. Verify .env file is in the project root

Setting Shows as Locked

Settings configured via environment variables are locked and cannot be changed via the admin UI. To unlock, remove the environment variable and restart.

Build Issues

Frontend Build Fails

# Clear build cache
rm -rf apps/web/dist apps/web/.turbo

# Rebuild
bun run build --filter=@sesame/web

TypeScript Errors

# Run type check to see all errors
bun run check-types

# Check specific package
bun run check-types --filter=@sesame/shared

Performance Issues

Slow Session Creation

• Check GitHub API rate limits
• Verify network connectivity to GitHub
• Large repositories take longer to clone

High Memory Usage

• Limit concurrent sessions
• Ensure sandboxes are being cleaned up after session completion
• Increase container memory for Docker deployments

Slow Frontend

• Check browser dev tools for network issues
• Verify SSE connection is stable
• Clear browser cache

Development Issues

Hot Reload Not Working

# Restart the dev server
# Ctrl+C to stop, then:
bun run dev

Port Already in Use

# Find what's using port 13531
lsof -i :13531

# Kill the process
kill -9 <PID>

Vite Proxy Errors

If the frontend can't reach the backend in development:

1. Ensure backend is running on port 13531
2. Check apps/web/vite.config.ts proxy configuration
3. Look for CORS errors in browser console

Getting Help

If you can't resolve an issue:

1. Check existing GitHub Issues
2. Search the Discussions
3. Open a new issue with:
   • Sesame version
   • Deployment method (Docker, Bun, etc.)
   • Relevant logs
   • Steps to reproduce