Skip to main content

​
Overview

The Error schema defines the standard JSON envelope for all CLEO error responses. It provides a consistent structure for communicating errors to users and agents, including machine-readable error codes, human-readable messages, and actionable recovery suggestions.

​
Schema Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "schemaVersion": "1.0.0",
  "$id": "https://cleo-dev.com/schemas/v1/error.schema.json",
  "title": "Claude-TODO Error Envelope",
  "description": "Standard JSON envelope for all cleo error responses",
  "type": "object",
  "required": ["_meta", "success", "error"],
  "additionalProperties": false
}

​
Properties

​
Root Properties

PropertyTypeRequiredDescription
$schemastringNoSchema URL for validation (must be https://cleo-dev.com/schemas/v1/error.schema.json)
_metaobjectYesResponse metadata
successbooleanYesAlways false for error responses
errorobjectYesError details

​
_meta Object

PropertyTypeRequiredDescription
formatstringNoOutput format identifier (always “json”)
versionstringYesCLEO version (semver format)
commandstringYesCommand name that generated this error
timestampstringYesISO-8601 UTC timestamp of error generation

​
error Object

PropertyTypeRequiredDescription
codestringYesError code with E_ prefix (e.g., E_TASK_NOT_FOUND)
messagestringYesHuman-readable error message
exitCodeintegerYesShell exit code (1-127)
recoverablebooleanNoWhether the error can be recovered from
suggestionstring/nullNoSuggested action to resolve the error
fixstring/nullNoConcrete command to fix the error (copy-paste ready)
alternativesarrayNoAlternative recovery actions with executable commands
contextobjectNoAdditional error context (varies by error type)

​
alternatives Array Items

PropertyTypeRequiredDescription
actionstringYesShort description of what this alternative does
commandstringYesExecutable command (copy-paste ready)

​
Error Codes

The schema defines the following error codes:
Error CodeDescription
E_TASK_NOT_FOUNDRequested task does not exist
E_TASK_ALREADY_EXISTSTask with this ID already exists
E_TASK_INVALID_IDTask ID format is invalid
E_TASK_INVALID_STATUSInvalid task status value
E_FILE_NOT_FOUNDRequired file not found
E_FILE_READ_ERRORUnable to read file
E_FILE_WRITE_ERRORUnable to write file
E_FILE_PERMISSIONPermission denied for file operation
E_VALIDATION_SCHEMAJSON Schema validation failed
E_VALIDATION_CHECKSUMChecksum validation failed
E_VALIDATION_REQUIREDRequired field missing
E_INPUT_MISSINGRequired input not provided
E_INPUT_INVALIDInput value is invalid
E_INPUT_FORMATInput format is incorrect
E_DEPENDENCY_MISSINGRequired dependency not found
E_DEPENDENCY_VERSIONDependency version mismatch
E_PHASE_NOT_FOUNDSpecified phase does not exist
E_PHASE_INVALIDInvalid phase value
E_SESSION_ACTIVESession already active
E_SESSION_NOT_ACTIVENo active session
E_UNKNOWNUnknown error occurred
E_NOT_INITIALIZEDCLEO not initialized
E_PARENT_NOT_FOUNDParent task not found
E_DEPTH_EXCEEDEDTask nesting depth exceeded
E_SIBLING_LIMITToo many sibling tasks
E_INVALID_PARENT_TYPEParent cannot have children
E_CIRCULAR_REFERENCECircular dependency detected
E_ORPHAN_DETECTEDTask without valid parent
E_HAS_CHILDRENCannot delete task with children
E_TASK_COMPLETEDOperation not allowed on completed task
E_CASCADE_FAILEDCascading operation failed
E_CANCEL_REASON_REQUIREDCancellation reason required
E_CHECKSUM_MISMATCHData integrity check failed
E_CONCURRENT_MODIFICATIONFile was modified concurrently
E_ID_COLLISIONID collision detected
E_SESSION_EXISTSSession already exists
E_SESSION_NOT_FOUNDSession not found
E_SCOPE_CONFLICTSession scope conflict
E_SCOPE_INVALIDInvalid session scope
E_TASK_NOT_IN_SCOPETask not in session scope
E_TASK_CLAIMEDTask already claimed by another session
E_SESSION_REQUIREDSession required for operation
E_SESSION_CLOSE_BLOCKEDCannot close session
E_FOCUS_REQUIREDTask focus required
E_NOTES_REQUIREDNotes required for operation

​
Examples

​
Basic Error Response

{
  "_meta": {
    "format": "json",
    "version": "1.0.0",
    "command": "cleo show",
    "timestamp": "2026-01-27T22:30:00Z"
  },
  "success": false,
  "error": {
    "code": "E_TASK_NOT_FOUND",
    "message": "Task T9999 not found in todo.json",
    "exitCode": 1,
    "recoverable": true,
    "suggestion": "Use 'cleo list' to see available tasks",
    "fix": "cleo list --status pending"
  }
}

​
Error with Alternatives

{
  "_meta": {
    "format": "json",
    "version": "1.0.0",
    "command": "cleo add",
    "timestamp": "2026-01-27T22:35:00Z"
  },
  "success": false,
  "error": {
    "code": "E_TASK_ALREADY_EXISTS",
    "message": "Task T0100 already exists",
    "exitCode": 1,
    "recoverable": true,
    "suggestion": "Choose a different task ID or update the existing task",
    "alternatives": [
      {
        "action": "List existing tasks",
        "command": "cleo list"
      },
      {
        "action": "Update existing task",
        "command": "cleo update T0100 --status active"
      }
    ],
    "context": {
      "existingTaskId": "T0100",
      "existingTaskTitle": "Sample Task"
    }
  }
}

​
Validation Error with Context

{
  "_meta": {
    "format": "json",
    "version": "1.0.0",
    "command": "cleo validate",
    "timestamp": "2026-01-27T22:40:00Z"
  },
  "success": false,
  "error": {
    "code": "E_VALIDATION_SCHEMA",
    "message": "todo.json failed schema validation",
    "exitCode": 1,
    "recoverable": true,
    "suggestion": "Run 'cleo validate --fix' to attempt automatic repair",
    "fix": "cleo validate --fix",
    "context": {
      "file": "todo.json",
      "errors": [
        {
          "path": "/tasks/0/status",
          "message": "Invalid enum value: 'in-progress'"
        }
      ]
    }
  }
}

​
Usage

The error schema is used throughout CLEO:
  • CLI Error Output: All cleo commands output errors in this format when using --format json
  • API Responses: Error responses from any CLEO API endpoints
  • Script Integration: Bash scripts can parse structured error responses
  • Agent Communication: LLM agents receive consistent error information

​
Exit Codes

Common exit codes used:
Exit CodeMeaning
1General error
2Invalid arguments
3File not found
4Permission denied
5Validation failed
6Task not found
10Session error
127Command not found

​
Recovery Patterns

Errors follow these recovery patterns:
  1. recoverable: true: User can fix the issue and retry
  2. fix provided: Copy-paste command to resolve
  3. alternatives provided: Multiple recovery options
  4. context provided: Additional details for debugging