⚠️ Troubleshooting

Common issues and solutions for cognitive workflows.

LLM Provider Issues

API Key Not Found

1
Error: ANTHROPIC_API_KEY not set

Solution:

1
2
export ANTHROPIC_API_KEY=sk-ant-...
# Or add to .env file

Token Budget Exceeded

1
Error: Agent 'semantic-mapper' exceeded token budget (1500 > 1000)

Solution:

• Reduce maxOutputTokens in agent config
• Make output schema more compact
• Use a more concise model

Rate Limit Hit

1
Error: Rate limit exceeded for provider 'anthropic'

Solution:

1
2
3
4
5
# Configure backoff
policies:
  rateLimit:
    onLimit: "queue"  # Queue instead of reject
    retryAfter: 60

Schema Validation Issues

Output Schema Mismatch

1
2
3
Error: Agent output does not match schema
Expected: { "findings": array }
Got: { "results": array }

Solution:

• Review agent prompt for correct field names
• Use schema validation in prompt

Missing Required Field

1
Error: Missing required field 'confidence'

Solution:

• Add explicit instruction in prompt
• Check schema requirements

Workflow Issues

No Convergence

1
Error: Workflow did not converge after 5 rounds

Solution:

1
2
3
execution:
  maxRounds: 10              # Increase rounds
  convergenceThreshold: 0.9  # Lower threshold

State Explosion

1
Error: State size exceeded limit (100KB > 50KB)

Solution:

1
2
3
4
5
validator:
  checks:
    - type: "state-size"
      maxBytes: 100000       # Increase limit
      onViolation: "clip"    # Clip instead of block

Identity Drift

1
Error: ConceptId changed from 'sea:customer:001' to 'sea:client:001'

Solution:

• Enable identity persistence check
• Add explicit identity instructions to prompts

Agent Issues

Agent Not Responding

1
Error: Agent 'semantic-mapper' timed out

Solution:

1
2
3
execution:
  agentTimeout: 30  # seconds
  retries: 3

Invalid Tool Call

1
Error: Agent requested unauthorized tool 'write-file'

Solution:

• Check agent tools list
• Add tool to authorized list if appropriate

Debug Commands

1
2
3
4
5
6
7
8
9
10
11
# View workflow state
just cognitive-inspect --workflow-id <id>

# View agent outputs
just cognitive-trace --workflow-id <id> --agent semantic-mapper

# Validate configuration
just cognitive-validate --config router-config.yaml

# Test agent in isolation
just cognitive-test-agent --agent <id> --input "test query"

Getting Help

1
2
3
4
5
# View logs
just cognitive-logs --workflow-id <id>

# Export debug bundle
just cognitive-debug-export --workflow-id <id>