OfficeCLI Error Codes and Recovery Patterns for AI Self-Correction: A Technical Guide

OfficeCLI returns deterministic JSON error payloads containing canonical codes like not_found and unsupported_property, alongside human-readable messages and actionable suggestions, enabling AI agents to implement self-healing document manipulation workflows.

OfficeCLI from iOfficeAI is designed specifically for agentic automation, providing structured error responses that enable autonomous systems to recover from mistakes without human intervention. Unlike traditional CLI tools that return unstructured text, every command emits machine-parseable JSON containing precise error codes and remediation hints. This architecture allows AI agents to handle edge cases—such as invalid property names or out-of-bound paths—by programmatically adjusting arguments and retrying operations until successful.

How OfficeCLI Structures Error Responses

The CLI wraps every operation in a consistent JSON envelope that distinguishes success from failure states. When errors occur, the response includes machine-readable identifiers that agents can map to specific recovery strategies.

The JSON Error Schema

Error objects returned by OfficeCLI contain four primary fields that enable automated parsing:

• error – Human-readable description of what went wrong
• code – Canonical error identifier (e.g., not_found, invalid_value, unsupported_property)
• suggestion – Recommended fix or valid range for the parameter
• path / part – Location within the document where the error occurred (when applicable)

In src/officecli/ResidentServer.cs (lines 715-743), the CLI creates the final response envelope, ensuring that both resident-mode and standard CLI paths emit a consistent format prefixed with "Error:". Meanwhile, src/officecli/CommandBuilder.cs (lines 416-507) implements the WriteError method, which centralizes the formatting of these JSON error objects across all command types.

Core Error Codes for AI Agents

According to the README documentation (lines 667-680), OfficeCLI exposes a deterministic set of error codes that agents can rely on for branching logic. The most common codes encountered during document manipulation include:

not_found – The specified path (e.g., /body/p[99]) does not exist in the document. The suggestion field typically returns the valid range (e.g., "Valid range: 1-12").

invalid_value – The value provided for a property is outside acceptable constraints or malformed.

unsupported_property – The property name supplied to a set command does not match the schema. The suggestion field often contains a fuzzy match recommendation (e.g., "Did you mean 'color'?").

AI Self-Correction Workflow

OfficeCLI enables a four-step recovery loop that allows agents to operate autonomously on documents of unknown structure.

Step 1: Parse the Error Payload

When a command returns a non-zero exit code, the agent extracts the code and suggestion fields from the JSON response. This eliminates the need for string parsing or regex matching on error messages.

officecli set report.docx /body/p[1]/r[1] --prop colr=red --json

This returns:

{
  "success": false,
  "error": {
    "error": "Property 'colr' not recognized",
    "code": "unsupported_property",
    "suggestion": "Did you mean 'color'?"
  }
}

Step 2: Query Document Structure

For not_found errors, agents can introspect the document to discover valid paths before retrying. The --depth flag limits the recursion to prevent overwhelming payloads.

officecli get report.docx /body --depth 1 --json

This returns the available children, allowing the agent to select a valid index or path component.

Step 3: Apply Automated Fixes

Using the suggestion field or the discovered valid parameters from the query step, the agent re-issues the corrected command:

officecli set report.docx /body/p[1]/r[1] --prop color=red --json

Successful execution returns:

{
  "success": true,
  "path": "/body/p[1]/r[1]"
}

Implementation Details in the Source Code

The reliability of OfficeCLI's error handling stems from centralized implementations in two core files.

src/officecli/ResidentServer.cs generates the final response envelope and embeds error handling logic specific to resident mode. Lines 715-743 ensure that error outputs maintain the "Error:" prefix consistently across execution modes.

src/officecli/CommandBuilder.cs serves as the central command dispatcher. The WriteError method (lines 416-507) formats exceptions into the standardized JSON structure, ensuring that higher-level commands like set, add, and query propagate errors uniformly.

src/officecli/McpServer.cs extends this error handling to JSON-RPC contexts, exposing the CLI over the Model Context Protocol (MCP) and propagating error objects to AI-tool integrations without transformation loss.

Practical Examples for Agent Development

The following patterns demonstrate how autonomous agents can handle edge cases programmatically.

Handling typos in property names:

# Initial attempt with typo triggers suggestion

officecli set report.docx /body/p[1]/r[1] --prop colr=red --json

# Agent parses suggestion and retries with 'color'

officecli set report.docx /body/p[1]/r[1] --prop color=red --json

Recovering from out-of-bounds access:

# Attempt to access paragraph 99 in a 12-paragraph document

officecli get report.docx /body/p[99] --json

# Returns: {"success":false,"error":{"code":"not_found","suggestion":"Valid range: 1-12"}}

# Agent lists available paragraphs and selects valid index

officecli get report.docx /body --depth 1 --json

Summary

• OfficeCLI from iOfficeAI emits structured JSON errors containing code, error, and suggestion fields for every failed operation.
• The error handling logic resides in ResidentServer.cs (lines 715-743) and CommandBuilder.cs (lines 416-507), ensuring consistent formatting across resident and standard modes.
• Canonical error codes like not_found, invalid_value, and unsupported_property enable agents to implement deterministic recovery branches.
• AI agents can achieve full autonomy by parsing error suggestions, querying document structure with --depth flags, and retrying with corrected parameters.
• The deterministic error format supports iterative correction loops, enabling autonomous document creation pipelines without human intervention.

Frequently Asked Questions

What fields does OfficeCLI include in its JSON error responses?

OfficeCLI error objects contain four key fields: error (human-readable description), code (canonical identifier like not_found), suggestion (recommended fix or valid range), and optionally path or part (indicating where the error occurred). This structure is implemented in CommandBuilder.WriteError and documented in the README (lines 667-680).

How should an AI agent recover from a not_found error in OfficeCLI?

When encountering a not_found error, the agent should parse the suggestion field for valid ranges, then query the document structure using officecli get <document> <parent-path> --depth 1 --json to discover available children. The agent can then select a valid path component and retry the original command with the corrected parameters.

Where is the error formatting logic implemented in the OfficeCLI source code?

The core error formatting resides in two locations: src/officecli/ResidentServer.cs (lines 715-743) creates the final response envelope with the "Error:" prefix, while src/officecli/CommandBuilder.cs (lines 416-507) contains the WriteError method that constructs the JSON error objects dispatched to callers.

Does OfficeCLI support integration with AI tools through the Model Context Protocol?

Yes, src/officecli/McpServer.cs exposes OfficeCLI over JSON-RPC via the Model Context Protocol (MCP), propagating the same structured error objects to AI-tool integrations. This allows agents consuming the MCP interface to receive identical error codes and suggestions as they would from the command line interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}