Skip to main content

Debugging Agents

When things go wrong, here’s how to diagnose and fix them.

Local Testing

Always test locally before deploying:
This runs your agent exactly as Castari does — prompt on stdin, response on stdout.

Debug Mode

Add debug output to stderr (doesn’t affect response):

Common Errors

”Agent not found”

Cause: Wrong slug or agent doesn’t exist. Fix:

“Agent not active”

Cause: Agent isn’t deployed or was stopped. Fix:

“castari.json not found”

Cause: Missing configuration file. Fix: Create castari.json in your agent root:

“npm install failed”

Cause: Dependency issues. Fix:
  1. Run npm install locally first
  2. Check package.json for errors
  3. Ensure all packages are published to npm

”Timeout exceeded”

Cause: Agent took too long (>120s default). Fix:
  • Optimize slow operations
  • Break complex tasks into smaller steps
  • Check for infinite loops

”Tool execution failed”

Cause: Error in tool handler. Fix:

“ANTHROPIC_API_KEY not set”

Cause: Missing API key. Fix: Castari injects this automatically. If you see this locally:

Debugging Tool Calls

Log Tool Inputs/Outputs

Validate Tool Schemas

Ensure your tool schemas match what Claude sends:

Debugging Claude Interactions

Log Messages

Check Stop Reasons

Environment Issues

Check Secrets

Make sure required secrets are set.

Check Agent Status

If status is error, redeploy:

Getting Help

If you’re stuck:
  1. Test locally: echo "prompt" | npm run dev
  2. Check status: cast agents get my-agent
  3. Redeploy: cast deploy
Still stuck? Open an issue on GitHub.

See Also

Sandboxes

Execution environment

cast invoke

CLI reference