Error Handling & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The error handling and logging system in the code-cli project is a multi-layered architecture designed to ensure system resilience, provide user feedback, and maintain a historical record of system failures for future prevention. It encompasses runtime error catching, specialized session recovery logic, and persistent logging of failures to a project-level knowledge base.
This system is critical for the autonomous nature of the agent, as it allows for automated retries of transient errors while providing clear diagnostic information for terminal failures. It also integrates with the Historical Retrieval System to ensure that once an error is encountered and understood, the agent avoids repeating the same mistake.
Session Error Handling and Recovery
The core agent loop implements a sophisticated retry mechanism for session-level errors. This logic distinguishes between "retryable" transient errors (such as network timeouts or rate limits) and "non-retryable" terminal errors (such as authentication failures or invalid API keys).
Retry Logic and Classification
When an error occurs during the ReAct loop, the agent evaluates the error message to determine if a recovery attempt is feasible. Retryable errors trigger an exponential backoff delay before the agent injects a "System Recovery" message into the conversation context to guide the LLM back to its task.
The diagram shows the decision flow when the agent encounters an exception during an instruction turn. Sources: src/core/agent.ts:1146-1215
| Error Category | Classification | Examples |
|---|---|---|
| Authentication | Non-Retryable | API key missing, Unauthorized, Access Denied |
| Billing/Quota | Non-Retryable | Payment required, Quota exceeded |
| Network | Retryable | ECONNRESET, Timeout, Service Unavailable |
| Logic/Format | Retryable | JSON parsing errors, Unexpected tokens |
| User Action | Non-Retryable | Payload too large, Context too long, Cancellation |
Sources: src/core/agent.ts:1537-1605
Persistent Failure Logging and Knowledge Synthesis
Beyond immediate error recovery, the project maintains a persistent record of failures at the workspace level. This is managed by the ProjectManager, which logs failures into a failures.jsonl file within the .autohand directory.
Failure Records
Each failure is recorded as a structured data point containing the tool used, the command executed, the specific error message, and the session context. This data is used to synthesize "Anti-Patterns"—sequences or actions that have historically failed in the specific project.
The relationship between a project and its historical failure logs. Sources: src/session/ProjectManager.ts:65-71, prd/historical-retrieval.md:104-108
Knowledge Synthesis
The system periodically updates a knowledge.json file by analyzing the failure logs. It calculates a "confidence" score for anti-patterns based on the frequency of occurrences, which the agent then uses to warn the user or self-correct before executing similar commands in future turns. Sources: src/session/ProjectManager.ts:145-188
Auto-Mode Circuit Breakers
In autonomous "Auto-Mode" sessions, the system employs "Circuit Breakers" to prevent the agent from getting stuck in infinite loops of failure or unproductive states.
Circuit Breaker Thresholds
The AutomodeState tracks specific metrics across iterations to detect stagnation. If a threshold is met, the session is automatically cancelled to prevent resource waste.
| Threshold Trigger | Default Limit | Description |
|---|---|---|
| No Progress | 3 Iterations | Consecutive turns with no file modifications. |
| Same Error | 5 Iterations | The agent encounters the exact same error hash repeatedly. |
| Test-Only | 3 Iterations | The agent only runs tests without making code changes. |
Sources: src/core/AutomodeState.ts:18-23, src/core/AutomodeState.ts:168-215
The interaction between the manager and state to enforce circuit breaker limits. Sources: src/core/AutomodeState.ts:168-175, tests/automode.spec.ts:254-265
Tool Execution Errors
Errors occurring within individual tool executions are caught by the ActionExecutor and returned as part of a ToolExecutionResult.
- Validation Errors: Before execution, parameters are validated (e.g.,
read_filechecking for apathargument). Sources: src/core/actionExecutor.ts:107-111 - Permission Blocks: The
PermissionManagerorSecurityScannermay block a command if it contains dangerous patterns or sensitive data, returning a specific block message instead of executing. Sources: src/core/actionExecutor.ts:602-610 - Shell Failures: For
run_command, the stdout and stderr are captured. If the exit code is non-zero, the result is marked as unsuccessful, but the error message is fed back to the LLM to allow for self-correction. Sources: src/core/actionExecutor.ts:310-330
Conclusion
The Error Handling & Logging system in code-cli transitions from simple exception catching to a proactive learning system. By classifying errors into retryable categories and persisting failures into a project-specific knowledge base, the system ensures that the AI agent becomes increasingly resilient and avoids repeating historical mistakes within a workspace.