Skip to main content

​
Installation Issues

Draft requires Python 3.11+. Check your version:
python3 --version
Install a newer version from python.org or via your package manager.
Draft requires Node.js 18+. Check your version:
node --version
Install via nvm or nodejs.org.
If port 8000 or 5173 is already in use:
npx draft-board --port 9000 --frontend-port 5174

​
Execution Issues

If Claude Code fails with a “nested session” error, it’s because Draft is running inside Claude Code itself. Draft automatically strips the CLAUDECODE and CLAUDE_CODE_ENTRYPOINT environment variables to prevent this, but if you encounter it, restart Draft from a regular terminal.
Make sure the CLI for your configured executor is in your PATH:
which claude    # For Claude Code
which cursor    # For Cursor
Install the CLI and try again.
When the AI agent exits without making any code changes, the ticket moves to BLOCKED with reason “no changes”. This usually means:
  • The ticket instructions are too vague
  • The agent couldn’t understand the codebase
  • The requested change was already implemented
Try editing the ticket with more specific instructions.
Check the evidence panel for detailed stdout/stderr. Common causes:
  • Tests not running in the worktree context
  • Missing dependencies in the worktree
  • Flaky tests unrelated to the changes

​
Configuration Issues

Draft looks for draft.yaml in the repository root (detected via git). If running from a subdirectory, it falls back to detecting the git root. Create the file at your repo root:
touch draft.yaml
Reset and re-run migrations:
cd backend
rm -f draft.db draft.db-shm draft.db-wal
source venv/bin/activate
alembic upgrade head
Ensure FRONTEND_URL in backend/.env matches your frontend URL:
FRONTEND_URL=http://localhost:5173

​
Getting Help