Troubleshooting

Common Issues

Startup Issues

Missing Tracker API Key

Symptom: Risoluto exits with missing_tracker_api_key on startup.Cause: tracker.api_key resolves to an empty value.Fix: Run the setup wizard at /setup and re-enter your Linear API key, or set the environment variable:

export LINEAR_API_KEY=lin_api_...

Missing Codex Auth

Symptom: account/read failure during startup.Cause: The Codex app-server cannot authenticate with the configured provider.Fix: Verify your auth mode:

Mode	Check
API Key	`echo $OPENAI_API_KEY` returns a valid key
Codex Login	Run `codex login` and re-upload `auth.json` via the setup wizard
Browser PKCE	Re-authenticate via the setup wizard at `/setup`

Port already in use

Symptom: EADDRINUSE: address already in use :::4000Cause: Another process is bound to the port.Fix:

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

# Use a different port
node dist/cli/index.js --port 4001

Master Key Mismatch

Symptom: secrets.enc decryption failure on startup.Cause: The MASTER_KEY environment variable doesn’t match the key used to encrypt secrets.Fix: Use the correct master key, or factory reset:

docker compose down -v && docker compose up --build -d

rm .risoluto/secrets.enc .risoluto/master.key

Factory reset deletes all stored credentials. You will need to re-run the setup wizard.

Agent Failures

Container OOM (Out of Memory)

Symptom: Agent exit code 137, OOMKilled=true in container inspect.Cause: The agent exceeded the container memory limit.Fix: Increase the memory allocation:

curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"sandbox":{"resources":{"memory":"8g"}}}}'

Verify OOM status:

docker inspect <container-id> | jq '.[0].State.OOMKilled'

Agent stalls (no progress)

Symptom: Issue stays in agent_running state with no new events.Cause: The agent is stuck — infinite loop, network timeout, or model API hang.Fix: Risoluto has two stall timeouts: codex.stallTimeoutMs (default: 5 minutes) kills silent turns, and agent.stallTimeoutMs (default: 20 minutes) kills the entire agent. To kill manually:

curl -s -X POST http://127.0.0.1:4000/api/v1/NIN-6/abort

Reduce the stall timeout for faster detection:

curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"agent":{"stallTimeoutMs":120000}}'

Required MCP Startup Failure

Symptom: thread/start failed because a required MCP server did not initializeCause: This is a Codex runtime error, not a Risoluto bug. The agent’s MCP configuration references a server binary that is missing or failing inside the container.Fix: Check codex.sandbox.extraMounts and ensure all required MCP server binaries are available inside the container. Verify with:

docker exec <container-id> which <mcp-binary>

Agent exhausted all retries

Symptom: Issue marked as failed after 5 attempts.Cause: The agent could not complete the task within the retry budget.Fix: Inspect the attempt timeline to understand why:

curl -s http://127.0.0.1:4000/api/v1/NIN-6/attempts | jq

Options:

Simplify the issue description
Increase agent.maxContinuationAttempts
Switch to a more capable model via per-issue override
Force a retry: transition the issue back to the trigger state

Docker Problems

Docker daemon not running

Symptom: Cannot connect to the Docker daemonFix:

# Linux
sudo systemctl start docker

# macOS / Windows
# Open Docker Desktop

Verify: docker info should complete without errors.

Sandbox image not found

Symptom: No such image: risoluto-codex:latestFix: Build the sandbox image:

bash bin/build-sandbox.sh

If using a custom image, verify it exists:

docker images | grep risoluto

Permission denied on Docker socket

Symptom: permission denied while trying to connect to the Docker daemon socketFix: Add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in, or:
newgrp docker

Network Issues

Linear API connection failures

Symptom: Poll errors with ECONNREFUSED or ETIMEDOUT to api.linear.app.Cause: Network connectivity or DNS issues, or Linear API outage.Fix:

# Test connectivity
curl -s https://api.linear.app/graphql -X POST \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ viewer { id } }"}'

Check Linear Status for outages.

OpenAI API rate limiting

Symptom: Agents fail with 429 status codes.Cause: Too many concurrent agents hitting your API rate limit.Fix: Reduce concurrency:

curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"agent":{"maxConcurrentAgents":3}}'

Invalid or expired credentials

Symptom: 401/403 errors from Linear, OpenAI, or GitHub APIs.Cause: Credentials have expired or been revoked.Fix: Re-enter credentials via the setup wizard at /setup. Risoluto validates credentials before storing them and surfaces the upstream error message.

Linear Integration

Issues not being picked up

Symptom: In Progress issues in Linear are not dispatched by Risoluto.Cause: The issue’s project or state doesn’t match Risoluto’s configuration.Fix:

# Check which project Risoluto is watching
curl -s http://127.0.0.1:4000/api/v1/runtime | jq '.tracker'

# Check the current poll state
curl -s http://127.0.0.1:4000/api/v1/state | jq '.queues'

Ensure the issue belongs to the configured project and is in a state that maps to the trigger state.

Webhook events not arriving

Symptom: Webhook is configured but Risoluto doesn’t react to issue changes.Cause: Webhook URL is unreachable from Linear’s servers, or the webhook secret doesn’t match.Fix: Verify webhook delivery in Linear’s webhook settings (Settings > API > Webhooks). Check that the webhook URL is publicly reachable (ngrok, Cloudflare Tunnel, or public IP).

Diagnostic Commands

System state

# Full runtime snapshot
curl -s http://127.0.0.1:4000/api/v1/state | jq

# Runtime metadata (version, data dir, provider)
curl -s http://127.0.0.1:4000/api/v1/runtime | jq

# Setup status
curl -s http://127.0.0.1:4000/api/v1/setup/status | jq

Issue inspection

# Issue detail with recent events
curl -s http://127.0.0.1:4000/api/v1/NIN-6 | jq

# All attempts for an issue
curl -s http://127.0.0.1:4000/api/v1/NIN-6/attempts | jq

# Single attempt with full event timeline
curl -s http://127.0.0.1:4000/api/v1/attempts/<attempt-id> | jq

CLI log inspector

# Inspect by issue identifier
./risoluto MT-42

# Inspect by attempt ID
./risoluto --attempt <attempt-id>

# Use a custom data directory
./risoluto NIN-3 --dir /var/lib/risoluto

Container inspection

# List running agent containers
docker ps --filter label=risoluto.issue

# Filter by specific issue
docker ps --filter label=risoluto.issue=NIN-5

# View container logs
docker logs <container-id>

# Check for OOM kills
docker inspect <container-id> | jq '.[0].State.OOMKilled'

Environment Variables

Variable	Default	Description
`LOG_LEVEL`	`info`	Pino log level (`debug` for verbose output)
`RISOLUTO_LOG_FORMAT`	`logfmt`	Log format: `logfmt` or `json`
`SENTRY_DSN`	—	Error tracking endpoint
`LINEAR_API_KEY`	—	Linear API key (alternative to wizard setup)
`OPENAI_API_KEY`	—	OpenAI API key (alternative to wizard setup)
`GITHUB_TOKEN`	—	GitHub PAT for PR creation

Set LOG_LEVEL=debug for verbose diagnostic output when troubleshooting startup, dispatch, or agent lifecycle issues. This logs every poll cycle, workspace operation, and container lifecycle event.

What’s Next

Observability

Prometheus metrics, SSE events, audit logs, and data persistence.

FAQ

Common questions about models, privacy, and configuration.

Monitoring Stack

Set up Prometheus and Grafana for dashboards and alerting.

Security

Secure the API with write tokens and bind address controls.

Get Started

Core Concepts

Guides

Recipes

Operating

Common Issues

Startup Issues

Agent Failures

Docker Problems

Network Issues

Linear Integration

Diagnostic Commands

System state

Issue inspection

CLI log inspector

Container inspection

Environment Variables

What’s Next

Observability

FAQ

Monitoring Stack

Security

​Common Issues

​Startup Issues

​Agent Failures

​Docker Problems

​Network Issues

​Linear Integration

​Diagnostic Commands

​System state

​Issue inspection

​CLI log inspector

​Container inspection

​Environment Variables

​What’s Next

Observability

FAQ

Monitoring Stack

Security

Common Issues

Startup Issues

Agent Failures

Docker Problems

Network Issues

Linear Integration

Diagnostic Commands

System state

Issue inspection

CLI log inspector

Container inspection

Environment Variables

What’s Next