Back to Docs

How to Debug Container Failures

Troubleshoot when agents don't start or crash unexpectedly.

Common Symptoms

  • • Agent appears in tree but shows "error" status
  • • Chat shows "Container spawn failed" message
  • • No output in chat panel
  • • Agent immediately goes to "idle" without working

Quick Diagnostics

1. Check the Error Message

In the chat panel, look for red error messages:

ERROR: Container spawn failed: [error details]

Common errors:

  • • "No API key configured": Missing OpenRouter key
  • • "Image not found": Container image issue
  • • "Out of memory": Exceeded 2GB RAM

2. Verify Your API Key

Go to Settings / Provider API Keys:

  • • Is a key saved? (should show masked: sk-or-v1-a****xyz)
  • • Is it valid? (test with provider directly)
  • • Does it have balance/credits?

3. Test Your Container Locally

For custom agents, test locally first:

# Pull and test your image locally
docker run --rm -it \
  -e FILEPATH_API_KEY="$YOUR_KEY" \
  -e FILEPATH_TASK="test" \
  your-image:tag

# Send test input
echo '{"type":"message","content":"test"}' | docker run -i \
  -e FILEPATH_API_KEY="$YOUR_KEY" \
  your-image:tag

Common Issues & Fixes

Issue: "No API key configured"

Cause: User hasn't added OpenRouter/OpenAI key in Settings

Fix:

  1. Go to Settings / Provider API Keys
  2. Add your API key
  3. Retry spawning agent

Issue: Container spawns but no output

Causes: Buffering, wrong format, or silent crash

Fix — Force stdout flush:

// BAD: Buffered output
console.log(JSON.stringify({}...));

// GOOD: Force flush
process.stdout.write(JSON.stringify({}...) + '\n');

Issue: Agent dies after ~5 minutes

Cause: Idle timeout (expected behavior)

Containers sleep after 5 minutes of idle time to save resources. Send a message to wake it up.

Issue: Out of Memory (OOM)

Symptoms: Agent dies during heavy operations, partial output then stops

Cause: Exceeded 2GB RAM limit

Workarounds:

  • Process files in chunks, not all at once
  • Use streaming operations
  • Split work across multiple child agents

Getting Help

If none of these steps resolve the issue:

  1. Check browser DevTools / Network tab for WebSocket errors
  2. File an issue on GitHub with:
    • Agent type
    • Timestamp
    • Error message

Prevention

  • • Test locally first — Always verify custom agents locally
  • • Handle all errors — Wrap code in try/catch, emit error events
  • • Validate input — Don't assume stdin is valid JSON
  • • Emit status — Keep users informed with status events
  • • Flush output — Don't let Node.js/Python buffer stdout