# Complete Guide to OfficeCLI Error Codes: Interpretation and Fixes > Master OfficeCLI error codes with this guide. Understand and fix Word, Excel, and PowerPoint document issues programmatically using structured JSON error responses. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-07-09 --- **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: ```bash officecli get deck.pptx '/slide[99]' --json ``` Returns: ```json {"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: ```bash officecli set deck.pptx '/slide[1]/shape[1]' --prop fill="blurple" --json ``` Returns: ```json {"success":false,"error":{"error":"Invalid color value 'blurple'","code":"invalid_value","suggestion":"Use hex #RRGGBB, named color, or theme slot"}} ``` Misspelled property name: ```bash officecli set deck.pptx '/slide[1]/shape[1]' --prop colr="#FF0000" --json ``` Returns: ```json {"success":false,"error":{"error":"Property 'colr' is not supported","code":"unsupported_property","suggestion":"Did you mean 'color'?"}} ``` Path syntax error: ```bash officecli get deck.pptx '/slide[1/shape[2]' --json ``` Returns: ```json {"success":false,"error":{"error":"Malformed element path","code":"invalid_path","suggestion":"Check brackets and escape special characters"}} ``` Missing required property: ```bash officecli add deck.pptx '/' --type slide --json ``` Returns: ```json {"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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js), [`watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-overlay.js)). - **[`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js), while [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) defines the plugin-level error response format.