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: 
cd my-agent
echo "What files are here?" | npm run dev
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): 
console.error('[DEBUG] Starting agent...');
console.error(`[DEBUG] Prompt: ${prompt}`);
console.error(`[DEBUG] Executing tool: ${toolName}`);

​
Common Errors

​
”Agent not found”

Cause: Wrong slug or agent doesn’t exist. Fix: 
cast agents list  # See correct slugs
cast invoke correct-slug "Hello"

​
“Agent not active”

Cause: Agent isn’t deployed or was stopped. Fix: 
cast agents get my-agent  # Check status
cast deploy               # Redeploy

​
“castari.json not found”

Cause: Missing configuration file. Fix: Create castari.json in your agent root: 
{
  "name": "my-agent",
  "version": "0.1.0",
  "entrypoint": "src/index.ts",
  "runtime": "node"
}

​
“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: 
// Add error handling
case "my_tool":
  try {
    return await executeTool(input);
  } catch (error) {
    console.error(`[ERROR] Tool failed: ${error.message}`);
    throw error;
  }

​
“ANTHROPIC_API_KEY not set”

Cause: Missing API key. Fix: Castari injects this automatically. If you see this locally: 
export ANTHROPIC_API_KEY=your-key
echo "Hello" | npm run dev

​
Debugging Tool Calls

​
Log Tool Inputs/Outputs

async function executeTool(name: string, input: any): Promise<string> {
  console.error(`[TOOL] ${name} called with:`, JSON.stringify(input));

  const result = await doToolWork(name, input);

  console.error(`[TOOL] ${name} returned:`, result.substring(0, 100));
  return result;
}

​
Validate Tool Schemas

Ensure your tool schemas match what Claude sends: 
// Schema says required: ["path"]
// Make sure you handle missing path
case "read_file":
  if (!input.path) {
    throw new Error("path is required");
  }
  return fs.readFileSync(input.path, "utf-8");

​
Debugging Claude Interactions

​
Log Messages

async function runAgent(prompt: string) {
  const messages = [{ role: "user", content: prompt }];

  while (true) {
    console.error(`[CLAUDE] Sending ${messages.length} messages`);

    const response = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      messages,
      tools
    });

    console.error(`[CLAUDE] Stop reason: ${response.stop_reason}`);
    console.error(`[CLAUDE] Content blocks: ${response.content.length}`);

    // ... rest of loop
  }
}

​
Check Stop Reasons

Stop ReasonMeaning
end_turnClaude finished responding
tool_useClaude wants to use a tool
max_tokensHit token limit
stop_sequenceHit a stop sequence

​
Environment Issues

​
Check Secrets

cast secrets list my-agent
Make sure required secrets are set.

​
Check Agent Status

cast agents get my-agent

Name:        My Agent
Slug:        my-agent
Status:      active
Sandbox ID:  sbx_xyz789
If status is error, redeploy: 
cast deploy

​
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