---
title: 'Troubleshooting Agent Customization'
section: 'agents'
tags: ['troubleshooting', 'debugging', 'agents']
order: 5
---

# Troubleshooting Agent Customization

Quick fixes for common agent customization issues.

## Quick Fix Checklist

1. **Restart Codebuff** to reload agent definitions
2. **Check TypeScript syntax:** Run `bun run typecheck` in your `.agents/` directory
3. **Verify file paths** are relative to project root
4. **Ensure your agent exports a default definition**

## Common Errors

### "Agent not found"

```text
Error: Agent 'my-custom-agent' not found
```

**Fix:** Check agent ID spelling, file location (`.agents/`), and that your TypeScript file has `export default definition`

### "Invalid spawnable agent"

```text
Validation error: spawnableAgents contains invalid agent 'researcher-typo'
```

**Fix:** Check spelling against [built-in agents list](/docs/agents/overview#h2-built-in-agents), use exact IDs

### "Path not found" Error

```text
Error: Cannot resolve prompt file './my-prompt.md'
```

**Causes:**

- File doesn't exist at specified path
- Incorrect relative path resolution
- File permissions issue

**Solutions:**

1. Use paths relative to project root: `.agents/templates/my-prompt.md`
2. Verify file exists: `ls -la .agents/templates/my-prompt.md`
3. Check file permissions are readable

## JSON Schema Issues

### Invalid Override Type

```json
{
  "systemPrompt": {
    "type": "add", // ❌ Invalid
    "content": "..."
  }
}
```

**Fix:** Use valid override types:

```json
{
  "systemPrompt": {
    "type": "append", // ✅ Valid: append, prepend, replace
    "content": "..."
  }
}
```

### Missing Required Fields

```typescript
// ❌ Missing required fields for new agents
const definition = {
  id: 'my-agent',
  displayName: 'My Agent'
}
```

**Fix:** Include all required fields for new agents:

```typescript
import type { AgentDefinition } from './types/agent-definition'

const definition: AgentDefinition = {
  id: 'my-agent',
  displayName: 'My Agent',
  model: 'anthropic/claude-sonnet-4.5',
  toolNames: ['read_files', 'write_file', 'end_turn'],
  instructionsPrompt: 'Process the user\'s request...',
}

export default definition
```

### "Path not found"

**Fix:** Use project root relative paths: `.agents/templates/my-prompt.md`, verify file exists

## Agent Behavior Issues

### Agent Not Using Custom Prompts

**Symptoms:**

- Agent behaves like default version
- Custom instructions ignored

**Debug Steps:**

1. Check override is properly applied:

```bash
# Restart Codebuff to reload templates
codebuff
```

2. Verify override syntax:

```json
{
  "id": "CodebuffAI/reviewer", // ✅ Exact match required
  "override": true, // ✅ Must be true for overrides
  "systemPrompt": {
    "type": "append", // ✅ Valid override type
    "content": "Custom instructions..."
  }
}
```

### Agent Spawning Wrong Sub-agents

**Symptoms:**

- Unexpected agents being created
- Missing expected specialized agents

**Solutions:**

1. Check `spawnableAgents` configuration:

```json
{
  "spawnableAgents": {
    "type": "replace", // Use "replace" to override completely
    "content": ["researcher", "thinker"]
  }
}
```

2. Verify agent names are correct (no typos)

## Performance Issues

### Agent Taking Too Long

**Causes:**

- Complex prompts causing slow generation
- Too many tools enabled
- Large context from message history

**Solutions:**

1. Simplify prompts and remove unnecessary instructions
2. Limit `toolNames` to only required tools
3. Set `includeMessageHistory: false` for stateless agents
4. Use faster models for simple tasks:

```json
{
  "model": "openai/gpt-5-mini" // Faster model
}
```

### High Credit Usage

**Causes:**

- Using expensive models unnecessarily
- Agents spawning too many sub-agents
- Large context windows

**Solutions:**

1. Use cost-effective models:

```json
{
  "model": "google/gemini-2.5-flash" // More economical
}
```

2. Limit spawnable agents:

```json
{
  "spawnableAgents": [] // Prevent sub-agent spawning
}
```

## File Organization Issues

### Agents Not Loading

**Symptoms:**

- No custom agents available
- Validation errors on startup

**Debug Steps:**

1. Check directory structure:

```markdown
your-project/
├── .agents/
│   ├── my-agent.ts
│   ├── types/
│   │   └── agent-definition.ts
│   └── prompts/
│       └── my-prompts.md
```

2. Verify file permissions:

```bash
ls -la .agents/
```

3. Check TypeScript compiles:

```bash
cd .agents && bun run typecheck
```

## Best Practices for Debugging

### 1. Start Simple

Begin with minimal overrides and add complexity gradually:

```json
{
  "id": "CodebuffAI/reviewer",
  "override": true,
  "model": "anthropic/claude-sonnet-4.5"
}
```

### 2. Use Validation Tools

- TypeScript check: `cd .agents && bun run typecheck`
- File existence: `ls -la .agents/`
- Syntax check: Most editors highlight TypeScript errors

### 3. Check Logs

Restart Codebuff to see validation errors:

```bash
codebuff  # Look for error messages on startup
```

### 4. Test Incrementally

Add one override at a time to isolate issues:

1. Test basic override (model change)
2. Add simple prompt override
3. Add external file reference
4. Add tool modifications

### 5. Use Version Control

Track your agent templates in git to easily revert problematic changes:

```bash
git add .agents/
git commit -m "Add custom reviewer agent"
```

## Getting Help

1. Check logs for error messages on startup
2. Remove customizations until it works, then add back one at a time
3. Join [Discord](https://codebuff.com/discord)
4. See the [Agent Reference](/docs/agents/agent-reference)

## Quick Reference

### Valid Override Types

- `"append"` - Add to existing content
- `"prepend"` - Add before existing content
- `"replace"` - Replace entire content

### Required Fields for New Agents

- `id` — Unique identifier
- `displayName` — Human-readable name  
- `model` — The LLM to use (e.g., `anthropic/claude-sonnet-4.5`)
- `toolNames` — Array of tools the agent can use
- `instructionsPrompt` — What the agent should do

### Common File Paths

- Agent definitions: `.agents/*.ts`
- Type definitions: `.agents/types/agent-definition.ts`
- External prompts: `.agents/prompts/*.md`
