# How to Troubleshoot Common OfficeCLI Errors: A Complete Diagnostic Guide

> Troubleshoot common OfficeCLI errors like not_found and invalid_value with this diagnostic guide. Understand deterministic JSON error codes for precise path mismatch and schema violation diagnosis.

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

---

**OfficeCLI returns deterministic JSON error codes—such as `not_found` and `invalid_value`—that enable precise diagnosis of path mismatches, schema violations, and asset dependencies without manual OOXML inspection.**

OfficeCLI is a self-contained, cross-platform binary that lets AI agents and developers create, read, and modify Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files without requiring local Microsoft Office installation. When troubleshooting common OfficeCLI errors, understanding its three-layer architecture and structured error responses is essential for rapid resolution.

## Understanding the OfficeCLI Error Architecture

OfficeCLI organizes its functionality into three logical tiers, each with distinct error profiles:

- **L1 (Read Layer):** High-level commands like `view`, `get`, and `query` generate human-friendly extracts and outlines. Errors here typically indicate missing files or unsupported formats.
- **L2 (DOM Layer):** Path-based manipulation via `add`, `set`, `remove`, and `move` uses 1-based indexing (`/slide[1]/shape[2]`). Errors usually involve invalid paths or property schemas.
- **L3 (Raw XML Layer):** Direct XPath editing through `raw`, `raw-set`, and `add-part` exposes edge-cases where the DOM abstraction fails. Errors here often relate to malformed OOXML or namespace issues.

All commands support the `--json` flag, which returns structured error objects including error codes, affected paths, and corrective suggestions.

## Diagnosing Common Error Patterns

### Resolving `not_found` Errors

The `not_found` error indicates a path references a non-existent element, often due to out-of-range 1-based indices or incorrect element types.

To diagnose:

```bash
officecli view report.pptx outline --json | jq '.[] | select(.tag=="slide")'

```

This lists existing slides with their indices. Adjust your path to match the actual document structure. For example, if slide 50 doesn't exist but the outline shows 12 slides, use `/slide[12]` instead.

### Fixing `invalid_value` Schema Errors

This error occurs when property values don't match the expected format, such as malformed hex colors or invalid data types.

To troubleshoot:

```bash
officecli pptx set shape.fill --help

```

Consult the property schema for the correct format. For example, colors require a leading hash: `--prop fill="#00FF00"` rather than `fill="00FF00"`.

### Addressing Rendering Issues

Missing images, text overflow, or overlapping shapes produce visual errors without crashing the CLI.

Run the issues reporter:

```bash
officecli view report.pptx issues --json > issues.json

```

This generates a structured report of layout problems, missing alt text, and asset embedding failures.

### Handling Formula Evaluation Failures

Excel formulas failing to compute usually stem from typos in function names (OfficeCLI supports 350+ built-in functions) or missing `--json` flags that prevent result inspection.

Verify cell evaluation:

```bash
officecli get workbook.xlsx /Sheet1/A1 --json

```

Cross-reference the function name against the supported list in the project Wiki.

## Performance Troubleshooting

### Resident Mode for Batch Operations

If commands stall during large batch edits, you're likely spawning new processes for each mutation rather than using resident mode.

Prefix operations with `open` and close with `close`:

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

```

This keeps the document in memory, dramatically reducing latency compared to disk-based operations.

### Validation Failures

Exit code non-zero indicates OOXML schema violations. Run:

```bash
officecli validate report.pptx

```

This returns Exit Code 0 on success, helping CI/CD pipelines catch corrupted documents before deployment.

## Installation and Configuration Issues

OfficeCLI distributes as a single self-contained binary with embedded .NET runtime, eliminating most dependency errors. However, path and configuration issues can occur.

### PATH and Binary Location

If `officecli` is not recognized, ensure the binary is in your PATH:

```bash
officecli install

```

This copies the binary to your PATH and installs the [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) file into detected AI coding agents (Claude Code, Cursor, etc.).

### Configuration Conflicts

Runtime configuration lives in `~/.officecli/config.json`. If auto-updates cause instability, disable them:

```bash
officecli config autoUpdate false

```

## Practical Troubleshooting Examples

### Example 1: Diagnose Missing Slide

```bash

# List all slides to find correct index

officecli view report.pptx outline --json | jq '.[] | select(.tag=="slide")'

# Correct the path based on output

officecli set report.pptx '/slide[2]/shape[1]' --prop fill="#00FF00"

```

### Example 2: Batch Update Validation

```bash
cat > updates.json <<'EOF'
[
  {"command":"set","path":"/Sheet1!A1","props":{"value":"=SUM(B1:B10)"}},
  {"command":"set","path":"/Sheet1!B1","props":{"value":100}}
]
EOF

# Validate input before applying

officecli batch sales.xlsx --input updates.json --json

```

### Example 3: Quality Check Pipeline

```bash

# Generate issues report

officecli view report.pptx issues --json > issues.json

# Validate OOXML schema

officecli validate report.pptx

```

## Summary

Troubleshooting OfficeCLI effectively requires leveraging its deterministic JSON output and layered architecture:

- Use `view <file> outline --json` to resolve `not_found` path errors by inspecting actual document structure.
- Consult command-specific `--help` for property schemas when encountering `invalid_value` errors.
- Enable resident mode with `open` and `close` commands to prevent performance stalls during batch operations.
- Run `view <file> issues --json` and `validate` to catch rendering problems and OOXML schema violations.
- Reference the official troubleshooting Wiki at `github.com/iOfficeAI/OfficeCLI/wiki/troubleshooting` for edge-cases involving Raw XML (L3) manipulations.

## Frequently Asked Questions

### What does the "not_found" error mean in OfficeCLI?

The `not_found` error indicates that a path references an element that doesn't exist in the document, typically caused by using 0-based indexing instead of OfficeCLI's required 1-based indexing or referencing slides/shapes that exceed the document's actual count. Use `officecli view <file> outline --json` to list available elements and their correct indices before adjusting your command.

### How do I fix "invalid_value" errors when setting properties?

`invalid_value` errors occur when property values don't match the expected schema, such as omitting the hash symbol in hex color codes or providing strings where numbers are required. Consult the specific property schema by running `officecli <format> set <element> --help` (for example, `officecli pptx set shape.fill --help`) to verify the correct data format and accepted values.

### Why are my images not rendering in OfficeCLI output?

Missing images usually indicate that assets aren't properly embedded in the document or that image dimensions exceed their container bounds, causing overflow. Run `officecli view <file> issues --json` to generate a structured report identifying missing embedded assets and layout problems that prevent proper rendering in HTML or screenshot modes.

### How can I improve performance when making multiple edits to the same file?

Performance stalls occur when each command spawns a new process instead of using resident mode. Prefix your edit sequence with `officecli open <file>` to keep the document in memory, execute your `add`, `set`, or `remove` commands, then finalize with `officecli close <file>` to flush changes to disk, reducing latency significantly compared to individual disk-based operations.