Skip to main content

​
Common Issues

​
Configuration Errors

​
Missing Linear API Token

Symptom: 
Linear API token missing in WORKFLOW.md
Solution: Set the LINEAR_API_KEY environment variable or configure it in WORKFLOW.md: 
export LINEAR_API_KEY="your-api-token"
./bin/symphony ./WORKFLOW.md
Source: config.ex:398-410 (elixir/lib/symphony_elixir/…)

​
Missing Project Slug

Symptom: 
Linear project slug missing in WORKFLOW.md
Solution: Add the project_slug to your tracker configuration: 
tracker:
  kind: linear
  project_slug: "your-project-slug"
To find your project slug:
  1. Go to Linear
  2. Right-click on your project
  3. Copy the URL
  4. Extract the slug from the URL: https://linear.app/project/{slug}/issues
Source: config.ex:412-424 (elixir/lib/symphony_elixir/…)

​
Missing Codex Command

Symptom: 
Codex command missing in WORKFLOW.md
Solution: Configure the Codex command in your WORKFLOW.md: 
codex:
  command: "codex app-server"
  # or with custom model
  command: "codex app-server --model gpt-5.3-codex"
Source: config.ex:426-432 (elixir/lib/symphony_elixir/…)

​
Unsupported Tracker Kind

Symptom: 
Unsupported tracker kind in WORKFLOW.md: "github"
Solution: Use a supported tracker kind: 
tracker:
  kind: linear  # Supported: "linear" or "memory"
Source: config.ex:389-396 (elixir/lib/symphony_elixir/…)

​
Startup Issues

​
Workflow File Not Found

Symptom: 
Workflow file not found: /path/to/WORKFLOW.md
Solution:
1

Verify File Path

Check that the workflow file exists:
ls -la /path/to/WORKFLOW.md
2

Use Absolute Path

Provide an absolute path or use the default location:
./bin/symphony $(pwd)/WORKFLOW.md
3

Check File Permissions

Ensure the file is readable:
chmod 644 WORKFLOW.md
Source: cli.ex:54-71 (elixir/lib/symphony_elixir/…)

​
Supervisor Not Running

Symptom: 
Symphony supervisor is not running
Solution: This indicates Symphony failed to start properly. Check:
  1. Application dependencies are installed: 
    mix deps.get
  2. Configuration is valid: 
    mix validate
  3. Required services (database, network) are available
Source: cli.ex:174-178 (elixir/lib/symphony_elixir/…)

​
Runtime Issues

​
Agent Task Exited Unexpectedly

Symptom: 
Agent task exited for issue_id=issue_abc123 session_id=sess_xyz reason=:timeout; scheduling retry
Solution:
Configure longer timeouts in WORKFLOW.md:
codex:
  turn_timeout_ms: 7200000    # 2 hours (default: 1 hour)
  stall_timeout_ms: 600000    # 10 minutes (default: 5 minutes)
  read_timeout_ms: 10000      # 10 seconds (default: 5 seconds)
Source: config.ex:31-34 (elixir/lib/symphony_elixir/…)
Examine logs for the specific session:
grep "session_id=sess_xyz" ./log/symphony.log
Inspect the workspace for the failed issue:
ls -la /tmp/symphony_workspaces/ABC-123/
Symphony automatically schedules retries with exponential backoff:
  • Base delay: 10 seconds
  • Maximum backoff: 300 seconds (5 minutes)
Source: orchestrator.ex:14-30 (elixir/lib/symphony_elixir/…)

​
Orchestrator Snapshot Unavailable

Symptom: Dashboard shows “Orchestrator snapshot unavailable” Solution:
  1. Check Orchestrator Process: 
    # In IEx console
Process.whereis(SymphonyElixir.Orchestrator)
  2. Verify Snapshot Timeout: Increase the snapshot timeout if the orchestrator is slow: 
    # Default: 15 seconds
{:ok, snapshot} = Orchestrator.snapshot(Orchestrator, 30_000)
  3. Restart Symphony: If the orchestrator is deadlocked, restart the service
Source: http_server.ex:269-291 (elixir/lib/symphony_elixir/…)

​
Workspace Issues

​
Workspace Creation Failed

Symptom: 
Failed to create workspace for issue ABC-123
Solution:
1

Check Disk Space

Ensure sufficient space is available:
df -h /tmp/symphony_workspaces
2

Verify Workspace Root Permissions

The workspace root must be writable:
mkdir -p /tmp/symphony_workspaces
chmod 755 /tmp/symphony_workspaces
3

Check Hook Output

Review after_create hook logs for errors:
grep "after_create" ./log/symphony.log
Source: config.ex:227-232 (elixir/lib/symphony_elixir/…)

​
Hook Timeout

Symptom: 
Hook after_create timed out after 60000ms
Solution: Increase the hook timeout: 
hooks:
  timeout_ms: 120000  # 2 minutes
  after_create: |
    git clone --depth 1 https://github.com/org/repo.git .
    mise install
    mix deps.get
Source: config.ex:27 (elixir/lib/symphony_elixir/…)
Very long hook timeouts can block agent dispatch. Keep hooks fast and defer heavy operations to the Codex session.

​
HTTP Server Issues

​
Port Already in Use

Symptom: 
Failed to start HTTP server: address already in use
Solution:
1

Choose Different Port

Use a different port number:
./bin/symphony --port 4001 ./WORKFLOW.md
2

Find Conflicting Process

Identify what’s using the port:
lsof -i :4000
# or
netstat -tulpn | grep :4000
3

Kill Conflicting Process

Stop the conflicting service or change Symphony’s port

​
Connection Refused

Symptom: 
curl http://127.0.0.1:4000/api/v1/state
curl: (7) Failed to connect to 127.0.0.1 port 4000: Connection refused
Solution:
  1. Verify Server is Running: Check that Symphony was started with --port flag
  2. Check Host Binding: If binding to a different host, adjust the URL: 
    server:
  host: "0.0.0.0"  # Listen on all interfaces
  port: 4000
  3. Firewall Rules: Ensure firewall allows connections to the port
Source: http_server.ex:55-78 (elixir/lib/symphony_elixir/…)

​
Debugging Techniques

​
Enable Verbose Logging

Increase log detail by examining the structured logs: 
# Follow logs in real-time
tail -f ./log/symphony.log

# Filter by issue
grep "issue_id=ABC-123" ./log/symphony.log

# Filter by session
grep "session_id=sess_xyz" ./log/symphony.log

​
Inspect Orchestrator State

Use the API to inspect current state: 
curl -s http://127.0.0.1:4000/api/v1/state | jq .

​
Check Codex Process

Verify Codex processes are running: 
# List Codex processes
ps aux | grep "codex app-server"

# Count Codex processes
ps aux | grep -c "codex app-server"

# Check process tree
pstree -p $(pgrep -f "bin/symphony")

​
Inspect Workspace

Examine workspace contents for debugging: 
# List workspace directories
ls -la /tmp/symphony_workspaces/

# Check specific workspace
tree /tmp/symphony_workspaces/ABC-123/

# Review git status in workspace
cd /tmp/symphony_workspaces/ABC-123 && git status

​
Monitor Resource Usage

Track Symphony’s resource consumption: 
top -p $(pgrep -f "bin/symphony")

​
Error Recovery

​
Manual Workspace Cleanup

If workspaces are not cleaned up automatically: 
# Remove specific workspace
rm -rf /tmp/symphony_workspaces/ABC-123

# Clean all workspaces (WARNING: destructive)
rm -rf /tmp/symphony_workspaces/*
Only remove workspaces for issues that are no longer active. Running agents may fail if their workspace is deleted.

​
Force Restart Agent

To force restart a stuck agent:
  1. Identify the Codex process: 
    ps aux | grep "codex app-server" | grep ABC-123
  2. Kill the process: 
    kill -9 <pid>
  3. Symphony will detect the failure and schedule a retry
Source: orchestrator.ex:91-132 (elixir/lib/symphony_elixir/…)

​
Reset Retry State

If an issue is stuck in retry loop:
  1. Move the Linear issue to a terminal state (Done/Cancelled)
  2. Wait for Symphony to detect the change
  3. Move the issue back to an active state
  4. Symphony will start fresh with attempt count reset

​
Database Recovery

Symphony uses in-memory state (no persistent database). To reset all state: 
# Simply restart Symphony
kill <symphony-pid>
./bin/symphony ./WORKFLOW.md
Restarting Symphony will:
  • Clear all in-memory state
  • Clean up terminal workspaces
  • Re-poll Linear for active issues
  • Resume from fresh state

​
Getting Help

If you’re still experiencing issues:
  1. Check Logs: Review ./log/symphony.log for detailed error messages
  2. Verify Configuration: Ensure WORKFLOW.md is valid YAML with all required fields
  3. Test Codex: Run codex app-server manually to verify it works
  4. Check Network: Ensure Linear API is reachable
  5. Review Documentation: See the SPEC.md for implementation details
Symphony is prototype software presented as-is. For production use, implement your own hardened version based on the specification.

Build docs developers (and LLMs) love

Get started for freeTalk to us