# How to Troubleshoot OfficeCLI Issues: A Complete Diagnostic Guide > Troubleshoot OfficeCLI issues with this diagnostic guide. Learn to diagnose document manipulation failures using deterministic JSON errors, validation commands, and OfficeCLI's three-tier architecture without needing local Offi... - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-07-15 --- **OfficeCLI provides deterministic JSON error outputs, built-in validation commands, and a three-tier architecture that makes diagnosing document manipulation failures straightforward without requiring local Office installation.** OfficeCLI is a self-contained, cross-platform binary from the iOfficeAI/OfficeCLI repository that enables AI agents and developers to create, read, and modify Word, Excel, and PowerPoint files. When you need to troubleshoot OfficeCLI issues, understanding its layered architecture and diagnostic commands is essential for rapid resolution. ## Understanding OfficeCLI's Three-Tier Architecture OfficeCLI organizes functionality into three logical layers that determine how errors manifest and how you should approach debugging. ### L1 Read Layer The **L1 (Read)** layer provides high-level, human-friendly document views through commands like `view`, `get`, and `query`. This layer generates outlines, text extracts, and annotated HTML views. Errors here typically indicate file corruption or unsupported format features, which you can verify using `officecli view outline --json` to inspect document structure. ### L2 DOM Layer The **L2 (DOM)** layer handles structured element manipulation using stable, path-based addressing such as `/slide[1]/shape[2]`. Commands including `add`, `set`, `remove`, `move`, and `swap` operate at this level. When you encounter `not_found` errors, use `officecli view outline --json` to list existing elements and verify that your 1-based indices match the actual document structure. ### L3 Raw XML Layer The **L3 (Raw XML)** layer provides direct XPath-based editing via `raw`, `raw-set`, `add-part`, and `validate` commands. This serves as a fallback when specific OOXML properties aren't exposed in the DOM abstraction. Errors at this layer often involve malformed XML or invalid XPath expressions, which you can debug by comparing your modifications against the document's actual schema. ## Common OfficeCLI Issues and Diagnostic Strategies ### Resolving "not_found" Path Errors The `not_found` error indicates that a specified path does not exist in the document. This commonly occurs when using 1-based indices that exceed the document's actual element count. To diagnose, run: ```bash officecli view report.pptx outline --json | jq '.[] | select(.tag=="slide")' ``` Export the document structure, then adjust your path to match existing indices. ### Fixing "invalid_value" Property Errors `invalid_value` errors occur when property values don't match the accepted format for a specific element type. For example, color values must include the leading hash symbol (e.g., `#00FF00`). Consult the property schema by running: ```bash officecli pptx set shape.fill --help ``` Verify valid input formats before applying edits. ### Diagnosing Rendering and Layout Issues Missing images, text overflow, or overlapping shapes typically indicate asset embedding failures or container size constraints. Use: ```bash officecli view report.pptx issues --json ``` This generates a structured report of layout problems using the internal rendering engine implemented in `src/officecli/officecli.csproj`. ### Addressing Performance Stalls in Batch Operations When processing large batches of edits, spawning a new process for each command creates significant overhead. Switch to **resident mode** by prefixing your session with `officecli open `, which keeps the document in memory and automatically flushes to disk after idle periods or upon explicit `officecli close ` commands. ## Using Built-in Diagnostic Tools ### JSON Output for Structured Error Parsing All commands support the `--json` flag, which returns deterministic JSON output including success flags, affected paths, and structured error objects with codes like `"not_found"` or `"invalid_value"`. This format enables AI agents to programmatically detect failures and self-correct without parsing human-readable text. ### The Issues Report Command The `officecli view issues --json` command leverages the internal HTML rendering engine to identify layout problems, missing alt text, and text overflow. This runs entirely within the binary without requiring a GUI, making it suitable for CI/CD pipelines. ### Validation and Schema Checking Run `officecli validate ` to verify OOXML conformance. This command returns ExitCode 0 on success and identifies structural violations that could cause compatibility problems with Microsoft Office or other applications. ## Optimizing Performance with Resident Mode For workflows requiring multiple edits, **resident mode** eliminates process spawn overhead. Start a session with `officecli open `, execute your `add`, `set`, or `remove` commands, and close with `officecli close ` to ensure atomic writes to disk. This mode is particularly effective when combined with the `batch` command for replaying JSON edit sequences: ```bash officecli open deck.pptx officecli add deck.pptx / --type slide --prop title="Q4" officecli set deck.pptx '/slide[1]/shape[1]' --prop text="Revenue ↑ 25%" officecli close deck.pptx ``` ## Configuration and Installation Troubleshooting OfficeCLI stores runtime configuration in `~/.officecli/config.json`, where you can disable auto-updates by setting `autoUpdate` to `false`. If the binary fails to execute, verify that you used the `officecli install` command, which copies the self-contained executable (with embedded .NET runtime) to your PATH and installs the [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) file into detected AI coding agents. For platform-specific wrapper issues, inspect [`npm/officecli.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js) or the [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh)/`install.ps1` scripts located in the repository root. The [`npm/package.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/package.json) defines the wrapper publication if you encounter Node.js-specific path resolution errors. ## Summary - OfficeCLI's three-tier architecture (L1 Read, L2 DOM, L3 Raw XML) determines where and how errors occur - Use `view outline --json` to diagnose path errors and `view issues --json` to identify layout problems - Always use the `--json` flag for deterministic, machine-readable error output - Enable resident mode with `officecli open ` to eliminate performance bottlenecks during batch operations - Consult the property schema via `--help` flags to resolve invalid value errors - Reference the official wiki at https://github.com/iOfficeAI/OfficeCLI/wiki/troubleshooting for evolving diagnostic patterns ## Frequently Asked Questions ### Why does OfficeCLI return a "not_found" error when the element clearly exists? The `not_found` error typically indicates a mismatch between your path's 1-based indexing and the actual document structure. OfficeCLI uses 1-based indices for all path-based addressing (e.g., `/slide[1]/shape[2]`), and the error often occurs when indices are out of range. Run `officecli view outline --json` to export the exact element hierarchy and verify your path syntax against the actual indices. ### How do I fix color or formatting values that trigger "invalid_value" errors? `invalid_value` errors occur when property strings don't match the expected schema for that element type. For example, hexadecimal colors must include the leading `#` symbol (e.g., `#00FF00` rather than `00FF00`). To identify the correct format, run `officecli set --help` (such as `officecli pptx set shape.fill`) to view the property schema, or consult the [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) file installed by `officecli install` for type-specific documentation. ### Can OfficeCLI diagnose document rendering issues without a GUI? Yes, OfficeCLI includes a built-in HTML rendering engine that can identify layout problems without requiring Microsoft Office or a desktop environment. Use `officecli view issues --json` to generate a structured report of text overflow, missing images, and overlapping shapes. This functionality works in headless CI/CD environments because the rendering engine ships inside the self-contained binary at `src/officecli/officecli.csproj`. ### What is the best practice for troubleshooting slow batch operations? Performance stalls during batch editing usually occur when each command spawns a new process rather than using resident mode. Prefix your workflow with `officecli open ` to start a resident process that keeps the document in memory, execute your series of `set`, `add`, or `remove` commands, and finalize with `officecli close `. For atomic multi-step operations, use the `dump` command to serialize edits to JSON, then replay them with `officecli batch --input updates.json`.