Complete Guide to OfficeCLI Error Codes: Interpretation and Fixes

OfficeCLI error codes are structured JSON responses that include an error code, human-readable message, and suggested fix, enabling programmatic error handling across Word, Excel, and PowerPoint documents.

The iOfficeAI/OfficeCLI repository provides a command-line interface for automating Microsoft Office documents. When operations fail, OfficeCLI returns deterministic error codes as structured JSON objects, allowing AI agents and scripts to diagnose and resolve issues automatically without parsing unstructured text.

Understanding the Error Response Structure

OfficeCLI reports errors as structured JSON objects that include an error code, a human-readable message, and a suggested fix. These codes remain consistent across all commands and formats (Word, Excel, PowerPoint). When using the --json flag, the CLI returns a standardized response format that agents can inspect programmatically.

Common OfficeCLI Error Codes

According to the iOfficeAI/OfficeCLI source code, the following nine error codes represent the most frequently encountered failure modes when manipulating documents.

not_found

The not_found code indicates that the requested element (slide, shape, cell, etc.) does not exist. This typically occurs when trying to get or set a path that exceeds the document's element count.

invalid_value

The invalid_value code signals that a supplied property value is malformed or out of range. Common triggers include supplying a color in an unsupported format or providing a dimension that isn't a valid number.

unsupported_property

The unsupported_property code indicates the property name is not valid for the element type. This often results from misspelling a property (e.g., colr instead of color).

invalid_path

The invalid_path code means the path syntax is incorrect or cannot be parsed. This occurs when using unbalanced brackets or illegal characters in a path string.

unsupported_type

The unsupported_type code indicates the command does not support the file format or element type. For example, attempting to add a 3-D model to a Word document triggers this error.

missing_property

The missing_property code signifies that a required property was omitted from the command. Adding a slide without specifying a required title property triggers this response.

file_not_found

The file_not_found code indicates the target file does not exist on disk. Running officecli get missing.docx against a non-existent file produces this error.

file_locked

The file_locked code means the file is currently open or locked by another process. This commonly occurs when editing a document that is already open in Microsoft Office.

invalid_selector

The invalid_selector code indicates the query selector is syntactically wrong or uses unsupported operators. Using a CSS-like selector that contains an unknown pseudo-class triggers this error.

Practical Error Handling Examples

The following examples demonstrate how OfficeCLI error codes appear in practice when using the --json flag for structured output.

Retrieve a non-existent slide:

officecli get deck.pptx '/slide[99]' --json

Returns:

{"success":false,"error":{"error":"Slide 99 not found (total: 8)","code":"not_found","suggestion":"Valid Slide index range: 1-8"}}

Supply an invalid color value:

officecli set deck.pptx '/slide[1]/shape[1]' --prop fill="blurple" --json

Returns:

{"success":false,"error":{"error":"Invalid color value 'blurple'","code":"invalid_value","suggestion":"Use hex #RRGGBB, named color, or theme slot"}}

Misspelled property name:

officecli set deck.pptx '/slide[1]/shape[1]' --prop colr="#FF0000" --json

Returns:

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

Path syntax error:

officecli get deck.pptx '/slide[1/shape[2]' --json

Returns:

{"success":false,"error":{"error":"Malformed element path","code":"invalid_path","suggestion":"Check brackets and escape special characters"}}

Missing required property:

officecli add deck.pptx '/' --type slide --json

Returns:

{"success":false,"error":{"error":"Missing required property 'title'","code":"missing_property","suggestion":"Add --prop title=\"Your Title\""}}

Implementation Sources

According to the iOfficeAI/OfficeCLI source code, error codes are defined and implemented across several key files:

• README.md: Contains the official list of error codes and example error objects in the "Error codes" section.
• src/officecli/Resources/: Houses core command implementations that emit the structured error JSON (e.g., watch-sse-core.js, watch-overlay.js).
• plugins/plugin-protocol.md: Defines the plugin-level error response format for extensibility.

These sources collectively define the deterministic feedback mechanism that allows AI agents to automatically correct issues based on the specific error code returned.

Summary

• OfficeCLI error codes are consistent across Word, Excel, and PowerPoint formats.
• Error responses include a machine-readable code, human-readable message, and suggested fix.
• The --json flag enables programmatic inspection of errors for automation and AI agent integration.
• Nine common codes cover element retrieval (not_found), value validation (invalid_value), property names (unsupported_property), path syntax (invalid_path), file states (file_locked, file_not_found), and selector formats (invalid_selector).
• Source definitions reside in README.md and src/officecli/Resources/ implementations.

Frequently Asked Questions

What format does OfficeCLI use for error reporting?

OfficeCLI returns errors as structured JSON objects containing three fields: an error code, a descriptive message, and a suggested fix. When using the --json flag, the CLI wraps this in a response object with a success boolean set to false.

How can I handle OfficeCLI errors programmatically?

Parse the JSON response and inspect the code field to determine the error type. Each code corresponds to a specific failure mode (e.g., not_found for missing elements, invalid_value for malformed data), allowing your script or AI agent to apply targeted corrections based on the suggestion provided.

What causes the file_locked error code?

The file_locked error occurs when the target file is currently open or locked by another process, typically Microsoft Office. Close the document in the Office application before running OfficeCLI commands against it.

Where are OfficeCLI error codes defined in the source?

The canonical list of error codes is documented in README.md under the "Error codes" section. The actual emission of these codes occurs in src/officecli/Resources/ files such as watch-sse-core.js, while plugins/plugin-protocol.md defines the plugin-level error response format.

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