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

> Master OfficeCLI error codes and recovery patterns for AI self-correction. This guide details JSON error payloads and actionable suggestions for self-healing document workflows in iOfficeAI/OfficeCLI.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

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

```

This returns:

```json
{
  "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.

```bash
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:

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

```

Successful execution returns:

```json
{
  "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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:**

```bash

# 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:**

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 715-743) and [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) (lines 715-743) creates the final response envelope with the `"Error:"` prefix, while [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.