Troubleshooting

Comprehensive troubleshooting guide organized by user scenario. For configuration details, see Configuration.

Server Issues

Port already in use

Error:

Error: Port 8420 is already in use

Cause: Another process (possibly another Amelia server instance) is using the default port.

Solutions:

Find and kill the process using the port:

bash

lsof -i :8420          # Find process ID
kill <PID>             # Kill the process

Use a different port:

bash

amelia dev --port 9000
# or
export AMELIA_PORT=9000
amelia dev

Database initialization failed

Error:

RuntimeError: Failed to set WAL journal mode

Causes:

Insufficient file system permissions
Database file corrupted
SQLite version too old (< 3.7.0)

Solutions:

Check permissions on the database directory:
bash
```
ls -la ~/.amelia/
chmod 755 ~/.amelia/
```
1
2
Remove corrupted database and restart:
bash
```
rm -rf ~/.amelia/amelia.db*
amelia dev
```
1
2

Verify SQLite version:

bash

python3 -c "import sqlite3; print(sqlite3.sqlite_version)"
# Should be >= 3.7.0 for WAL mode support

Server unreachable

Error:

ServerUnreachableError: Cannot connect to Amelia server at http://127.0.0.1:8420

Cause: Server is not running.

Solution:

Start the server first:

bash

amelia dev

Then in another terminal, run your command:

bash

amelia start ISSUE-123

Workflow Issues

Workflow conflict (409)

Error:

WorkflowConflictError: Workflow abc123 already active for worktree /path/to/repo

Cause: A workflow is already running in the same worktree. Only one workflow per worktree is allowed.

Solutions:

List active workflows:
bash
```
amelia status
```
1

Cancel the existing workflow:

bash

# Via CLI (if available)
amelia cancel <workflow-id>

# Or via API
curl -X POST http://127.0.0.1:8420/api/workflows/<workflow-id>/cancel

Use a different worktree:

bash

git worktree add ../repo-issue-123 -b feature/issue-123
cd ../repo-issue-123
amelia start ISSUE-123

Rate limit exceeded (429)

Error:

RateLimitError: Concurrency limit exceeded: 5/5 workflows active

Cause: Maximum concurrent workflows limit reached (default: 5).

Solutions:

Wait for existing workflows to complete or cancel them:

bash

amelia status                 # Check active workflows
amelia cancel <workflow-id>   # Cancel if needed

Invalid workflow state (422)

Error:

InvalidStateError: Cannot approve workflow in status 'executing'

Cause: Operation is not valid for the workflow's current state. For example:

Trying to approve a workflow that's already executing
Trying to reject a completed workflow

Valid state transitions:

pending → in_progress (workflow started via amelia run)
pending → planning (workflow started with --plan flag for immediate planning)
planning → pending_approval (after Architect generates plan)
pending_approval → executing (after approval)
pending_approval → planning (after rejection with feedback)
executing → reviewing (after Developer completes changes)
reviewing → executing (after Reviewer requests fixes, if iteration < max)
reviewing → completed (after Reviewer approves)
Any state → cancelled (via cancel operation)
Any state → failed (on error)

Solution:

Check workflow status before performing operations:

bash

curl http://127.0.0.1:8420/api/workflows/<workflow-id>

Queue Workflow Issues

Workflow stuck in pending state

Cause: Workflow was queued but never started.

Solutions:

Start the workflow manually:
bash
```
amelia run <workflow-id>
```
1
Start all pending workflows:
bash
```
amelia run --all
```
1

Check if the workflow has a plan ready:

bash

curl http://127.0.0.1:8420/api/workflows/<workflow-id>
# Look for workflow_status field

Cannot start queued workflow (409)

Error:

WorkflowConflictError: Cannot start workflow - another workflow is active on this worktree

Cause: Only one workflow can be active (in_progress or blocked) per worktree at a time. Note: planning status does NOT block the worktree.

Solutions:

Wait for existing workflow to complete
Cancel the existing active workflow:
bash
```
amelia cancel <active-workflow-id>
```
1
Start the queued workflow after the active one completes

Workflow stuck in planning state

Cause: Workflow entered planning status but the Architect hasn't completed. This can happen if:

The Architect is still generating the plan (normal)
The Architect encountered an error during planning
The LLM API is slow or unresponsive

Solutions:

Check server logs for Architect errors:
bash
```
export LOGURU_LEVEL=DEBUG
amelia dev
```
1
2

Cancel and retry the workflow:

bash

amelia cancel <workflow-id>
amelia start <issue-id> --plan

Note: Workflows in planning status can be cancelled and do NOT block the worktree.

Plan not generating

Cause: The --plan flag runs the Architect in the background. Planning can fail silently.

Solutions:

Check server logs for Architect errors:
bash
```
export LOGURU_LEVEL=DEBUG
amelia dev
```
1
2

Verify the issue exists and is accessible:

bash

# For GitHub issues
gh issue view <issue-id>

Note: If planning fails, the workflow transitions back to pending state (or fails). Check the workflow_status field to see if planning completed.

Invalid worktree (400)

Error:

InvalidWorktreeError: Invalid worktree '/path/to/repo': not a git repository

Causes:

Path doesn't exist
Path is not a git repository
Insufficient permissions

Solutions:

Verify path exists and is a git repo:
bash
```
cd /path/to/repo
git status
```
1
2
Initialize git repository if needed:
bash
```
git init
```
1
Check permissions:
bash
```
ls -la /path/to/repo
```
1

Driver Issues

API driver: Agent fails to create plan file

Error:

Plan file not found after architect completed

Cause: Some models have unreliable tool-calling capabilities. The Architect agent requires the LLM to call a write_file tool to create the plan, but weaker models may:

Output the plan as text instead of calling the tool
Call the tool with incorrect parameters
Terminate before completing the required tool call

Solutions:

Create a new profile with a stronger model:

bash

amelia config profile create dev-strong --driver api --model "anthropic/claude-sonnet-4"
amelia config profile activate dev-strong

Or switch to the Claude driver (recommended for reliability):

bash

amelia config profile create dev-cli --driver claude
amelia config profile activate dev-cli

Models known to work well:

anthropic/claude-sonnet-4
anthropic/claude-haiku
openai/gpt-4o

Models that may have issues:

Smaller/cheaper models with limited instruction-following
Models without native tool-calling support
Models that tend to output markdown instead of using tools

API driver: Tool calls not executed

Error:

Agent completed but required tool was never called

Cause: The model produced output text instead of tool calls. This is a model capability issue, not a configuration problem.

Solution:

The API driver includes retry logic (up to 3 attempts) and fallback extraction, but some models consistently fail. Use a different model or switch to claude.

Installation Issues

No module named 'amelia'

Error:

ModuleNotFoundError: No module named 'amelia'

Cause: Dependencies not installed.

Solution:

Install dependencies:

bash

uv sync

If using uv tool install, reinstall:

bash

uv tool install --reinstall git+https://github.com/existential-birds/amelia.git

Configuration Issues

Profile not found

Error:

Error: Profile 'production' not found in settings.

Cause: Referenced profile doesn't exist in your configuration.

Solution:

Check available profiles:
bash
```
amelia config profile list
```
1

Create the missing profile:

bash

amelia config profile create production --driver claude --tracker github

Or use an existing profile:
bash
```
amelia start ISSUE-123 --profile dev
```
1

No profiles configured

Error:

text

Error: No profiles configured. Run 'amelia config profile create' to add one.

Cause: No profiles have been created yet.

Solutions:

Create a profile with CLI commands:

bash

# Create a profile with Claude driver (recommended for getting started)
amelia config profile create dev --driver claude --tracker none

# Or with API driver
amelia config profile create dev --driver api --model "anthropic/claude-sonnet-4" --tracker github

Set the active profile:
bash
```
amelia config profile activate dev
```
1
Verify configuration:
bash
```
amelia config profile show dev
```
1

Invalid API key

Error for OpenRouter driver:

Error: OPENROUTER_API_KEY environment variable not set

Cause: Using driver: api without credentials.

Solutions:

Driver → Required Credentials:

api → OPENROUTER_API_KEY
claude → Claude CLI authenticated (claude auth login)
codex → Codex CLI authenticated

Set API key:
bash
```
export OPENROUTER_API_KEY=sk-...
```
1

Or create a CLI-based profile (no API key needed):

bash

amelia config profile create dev-cli --driver claude
amelia config profile activate dev-cli

Tracker authentication failed

Error for JIRA:

ConfigurationError: Missing required JIRA environment variables: JIRA_BASE_URL

Required environment variables by tracker:

Tracker	Required Variables
`jira`	`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`
`github`	`gh` CLI authenticated (`gh auth login`)
`none`	None (for testing)

Solutions:

For JIRA:

bash

export JIRA_BASE_URL=https://yourcompany.atlassian.net
export JIRA_EMAIL=you@company.com
export JIRA_API_TOKEN=your-api-token

For GitHub:

bash

gh auth login

For testing without real tracker:

bash

amelia config profile create test --driver claude --tracker none
amelia config profile activate test

Issue not found

Error:

Error: Issue 'PROJ-999' not found

Causes:

Issue ID doesn't exist in tracker
Tracker authentication failed
Wrong tracker configured

Solutions:

Verify issue exists in your tracker (JIRA/GitHub)
Check tracker authentication (see above)

For testing, use none tracker:

bash

amelia config profile create test --driver claude --tracker none
amelia config profile activate test

The none tracker creates mock issues automatically for any ID.

Security Errors

Amelia includes security layers that block dangerous operations. These errors appear when an agent attempts a command that violates safety rules.

ShellInjectionError

Error:

ShellInjectionError: Blocked shell metacharacter detected: ';'

Cause: An agent tried to run a command containing shell metacharacters (;, |, &, $, `, (, ), <, >, {, }). Amelia blocks these to prevent shell injection attacks.

What to do: This is expected behavior — Amelia's agents execute commands individually, not as chained shell expressions. If you see this error repeatedly, the LLM may be generating unsafe commands. Try switching to a stronger model or using the claude driver.

BlockedCommandError

Error:

BlockedCommandError: Command 'sudo' is blocked for security reasons

Cause: An agent tried to run a privileged or dangerous command. Blocked commands include: sudo, su, chmod +s, chown, chroot, systemctl, shutdown, reboot, mkfs, dd, fdisk, and others.

What to do: These commands cannot be executed through Amelia. If your workflow requires privileged operations:

Run them manually before starting the workflow
Configure your environment so agents don't need elevated permissions

DangerousCommandError

Error:

DangerousCommandError: Dangerous command pattern detected

Cause: An agent tried to run a command matching a known destructive pattern, such as rm -rf /, curl ... | sh, or writing to raw devices.

What to do: This is a safety guardrail. If you see this error, the agent attempted something destructive — likely due to a poorly constrained task description. Refine your issue description to be more specific about the expected approach.

PathTraversalError

Error:

PathTraversalError: Path '../../../etc/passwd' resolves to '/etc/passwd' which is outside allowed directories

Cause: An agent tried to read or write a file outside the allowed directory (the worktree root).

What to do: Agents are sandboxed to the repository root. If you need files outside the project, copy them into the worktree before starting the workflow.

Sandbox Issues

Docker Sandbox Issues

Docker not running or not installed

Error:

text

DockerException: Error while fetching server API version

Cause: Docker Desktop or the Docker daemon is not running, or Docker is not installed.

Solution:

Ensure Docker Desktop (macOS/Windows) or the Docker daemon (Linux) is running:

bash

docker info    # Verify Docker is running

Image build failures

Error:

text

Error building sandbox base image

Cause: The first sandbox run builds a base image using scripts/build-sandbox-base.sh, which can take 5-15 minutes. Build failures are often caused by insufficient Docker disk space or network issues during package installation.

Solutions:

Check Docker disk space:

bash

docker system df          # Show disk usage
docker system prune -a    # Free up space (removes unused images)

Manually run the build script to see full output:
bash
```
./scripts/build-sandbox-base.sh
```
1

Container startup failures

Error:

text

Container amelia-sandbox-<profile_name> failed to start

Cause: A stale container from a previous run may be blocking the new container.

Solutions:

Check for existing containers:

bash

docker ps -a --filter name=amelia-sandbox-

Remove stale containers:

bash

docker rm -f amelia-sandbox-<profile_name>

Port conflict on 8430

Error:

text

Bind for 0.0.0.0:8430 failed: port is already allocated

Cause: The LLM proxy runs on port 8430 by default. Another process or sandbox container is using this port.

Solutions:

Find and kill the process using the port:

bash

lsof -i :8430          # Find process ID
kill <PID>             # Kill the process

Remove stale sandbox containers that may be holding the port:

bash

docker ps -a --filter name=amelia-sandbox-
docker rm -f <container_name>

Network allowlist blocking required hosts

Error:

text

Connection refused / timeout when agent tries to reach external service

Cause: Sandbox network allowlist is enabled but doesn't include hosts the agent needs to reach.

Solution:

Add required hosts to network_allowed_hosts in your sandbox configuration via the dashboard at Settings → Profiles, or programmatically via the profile API (PUT /api/profiles/{name}).

Cleaning up all sandbox containers

To remove all Amelia sandbox containers at once:

bash

# Via Docker CLI
docker ps -aq --filter name=amelia-sandbox- | xargs -r docker rm -f

Or programmatically:

python

import asyncio
from amelia.sandbox.teardown import teardown_all_sandbox_containers

asyncio.run(teardown_all_sandbox_containers())

Daytona Cloud Sandbox Issues

Missing Daytona API key

Error:

text

ConfigurationError: DAYTONA_API_KEY environment variable not set

Cause: The DAYTONA_API_KEY environment variable is not set.

Solution:

Set the environment variable with your Daytona API key:

bash

export DAYTONA_API_KEY=your-daytona-api-key

Sandbox creation timeout

Error:

text

TimeoutError: Daytona sandbox creation timed out

Cause: The Daytona sandbox took longer than the configured timeout (default 120 seconds) to create. This can happen with large repositories or when the Daytona service is under load.

Solutions:

Increase the timeout by setting daytona_timeout in your sandbox configuration via the dashboard at Settings → Profiles, or programmatically via the profile API (PUT /api/profiles/{name}). The default is 120 seconds.
Check Daytona service status to ensure it is healthy.

Git clone failures in Daytona

Error:

text

Error cloning repository in Daytona sandbox

Cause: The repo_url is not set in the sandbox configuration, or the repository is private and requires authentication.

Solutions:

Ensure repo_url is set in your sandbox configuration via the dashboard at Settings → Profiles, or programmatically via the profile API.
For private repositories, set the GitHub token:
bash
```
export AMELIA_GITHUB_TOKEN=ghp_your-token
```
1

Network allowlist not supported with Daytona

Error:

text

ConfigurationError: network_allowlist_enabled is not supported with Daytona sandbox mode

Cause: The network_allowlist_enabled setting is a Docker-only feature and cannot be used with Daytona cloud sandboxes.

Solution:

Disable the network allowlist by setting network_allowlist_enabled: false in your sandbox configuration via the dashboard at Settings → Profiles, or programmatically via the profile API.

Worker upload failures

Error:

text

Error uploading worker to Daytona sandbox

Cause: The Daytona API is unreachable or the API key lacks sufficient permissions.

Solutions:

Verify Daytona API connectivity:

bash

curl -H "Authorization: Bearer $DAYTONA_API_KEY" https://api.daytona.io/health

Check that your API key has the required permissions for sandbox creation and file upload.

General Sandbox Issues

CLI drivers don't work in sandbox mode

Error:

text

ConfigurationError: Container sandbox requires API driver. CLI driver containerization is not yet supported.

or:

text

ConfigurationError: Daytona sandbox requires API driver. CLI driver containerization is not yet supported.

Cause: CLI-based drivers (claude, codex) cannot be used with sandbox mode. Only the api driver supports sandboxed execution because it communicates with the LLM via API and proxies requests through the sandbox.

Solution:

Switch to the api driver in your profile configuration via the dashboard at Settings → Profiles, or when creating a profile:

bash

amelia config profile create dev --driver api --model "anthropic/claude-sonnet-4"

Health check failures

Error:

text

Sandbox health check failed — tearing down and recreating

Cause: The sandbox container or Daytona workspace became unhealthy. Amelia auto-recovers by tearing down the sandbox and recreating it.

Solutions:

Check logs for the underlying cause:
bash
```
export LOGURU_LEVEL=DEBUG
amelia dev
```
1
2

If the issue persists, manually clean up and restart:

bash

# For Docker
docker ps -aq --filter name=amelia-sandbox- | xargs -r docker rm -f

# Then restart
amelia dev

Common Workflow Scenarios

Fresh installation not working

Checklist:

Dependencies installed: uv sync
Profile created: amelia config profile create dev --driver claude --activate
Tracker configured (or use --tracker none)
Driver credentials set (or use claude)
Server started: amelia dev

Can't start workflow

Checklist:

Server running: amelia dev
No existing workflow in worktree: amelia status
Valid git repository: git status
Issue ID valid (or use tracker: none)

Workflow stuck in pending_approval

Cause: Workflow is waiting for human approval.

Solution:

Approve or reject the plan:

bash

# Approve
amelia approve <workflow-id>

# Reject with feedback
amelia reject <workflow-id> "Please use a different approach"

Getting Help

If issues persist:

Check logs:
- Server logs: ~/.amelia/logs/server.log
- Workflow logs: ~/.amelia/logs/<workflow-id>/
Enable debug logging:
bash
```
export LOGURU_LEVEL=DEBUG
amelia dev
```
1
2
Check version:
bash
```
amelia --version
```
1
File an issue:
- GitHub: https://github.com/existential-birds/amelia/issues
- Include: error message, logs, amelia --version, OS/Python version

Troubleshooting ​

Server Issues ​

Port already in use ​

Database initialization failed ​

Server unreachable ​

Workflow Issues ​

Workflow conflict (409) ​

Rate limit exceeded (429) ​

Invalid workflow state (422) ​

Queue Workflow Issues ​

Workflow stuck in pending state ​

Cannot start queued workflow (409) ​

Workflow stuck in planning state ​

Plan not generating ​

Invalid worktree (400) ​

Driver Issues ​

API driver: Agent fails to create plan file ​

API driver: Tool calls not executed ​

Installation Issues ​

No module named 'amelia' ​

Configuration Issues ​

Profile not found ​

No profiles configured ​

Invalid API key ​

Tracker authentication failed ​

Issue not found ​

Security Errors ​

ShellInjectionError ​

BlockedCommandError ​

DangerousCommandError ​

PathTraversalError ​

Sandbox Issues ​

Docker Sandbox Issues ​

Docker not running or not installed ​

Image build failures ​

Container startup failures ​

Port conflict on 8430 ​

Network allowlist blocking required hosts ​

Cleaning up all sandbox containers ​

Daytona Cloud Sandbox Issues ​

Missing Daytona API key ​

Sandbox creation timeout ​

Git clone failures in Daytona ​

Network allowlist not supported with Daytona ​

Worker upload failures ​

General Sandbox Issues ​

CLI drivers don't work in sandbox mode ​

Health check failures ​

Common Workflow Scenarios ​

Fresh installation not working ​

Can't start workflow ​

Workflow stuck in pending_approval ​

Getting Help ​

Troubleshooting

Server Issues

Port already in use

Database initialization failed

Server unreachable

Workflow Issues

Workflow conflict (409)

Rate limit exceeded (429)

Invalid workflow state (422)

Queue Workflow Issues

Workflow stuck in pending state

Cannot start queued workflow (409)

Workflow stuck in planning state

Plan not generating

Invalid worktree (400)

Driver Issues

API driver: Agent fails to create plan file

API driver: Tool calls not executed

Installation Issues

No module named 'amelia'

Configuration Issues

Profile not found

No profiles configured

Invalid API key

Tracker authentication failed

Issue not found

Security Errors

ShellInjectionError

BlockedCommandError

DangerousCommandError

PathTraversalError

Sandbox Issues

Docker Sandbox Issues

Docker not running or not installed

Image build failures

Container startup failures

Port conflict on 8430

Network allowlist blocking required hosts

Cleaning up all sandbox containers

Daytona Cloud Sandbox Issues

Missing Daytona API key

Sandbox creation timeout

Git clone failures in Daytona

Network allowlist not supported with Daytona

Worker upload failures

General Sandbox Issues

CLI drivers don't work in sandbox mode

Health check failures

Common Workflow Scenarios

Fresh installation not working

Can't start workflow

Workflow stuck in pending_approval

Getting Help