# Debugging OfficeCLI Set and Add Command Failures: Fixing not_found and invalid_value Errors

> Fix OfficeCLI set and add command failures not_found and invalid_value errors. Use the --json flag to diagnose and resolve DOM path and schema validation issues quickly.

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

---

**OfficeCLI returns structured `not_found` and `invalid_value` error codes when DOM paths cannot be resolved or property values fail schema validation, and you can diagnose these quickly using the `--json` flag to expose the full error envelope with corrective suggestions.**

OfficeCLI is a cross-platform command-line tool for mutating Word, Excel, and PowerPoint documents through DOM-based paths. When `set` or `add` commands fail, the CLI emits machine-readable error codes that pinpoint exactly why the mutation was rejected. Understanding the difference between path resolution failures and schema validation errors allows you to fix document automation scripts without guesswork.

## Understanding OfficeCLI Error Codes

OfficeCLI implements every top-level command as a **CommandBuilder** object that wires command-line arguments to a **DocumentHandler** (Word, Excel, or PowerPoint). When mutations fail, the CLI returns a structured JSON error envelope containing three fields: `error` (human-readable description), `code` (machine-readable identifier), and `suggestion` (valid range or expected format).

### The not_found Error Code

The `not_found` code indicates that the **DOM path** does not exist in the current document. This occurs in three specific scenarios:

- **Index out of bounds**: Referencing `/slide[10]` in a presentation containing only 8 slides (slides are 1-based). The CLI returns `not_found` with a suggestion such as *"Valid Slide index range: 1-8"*.
- **Empty selector matches**: Using a selector like `Sheet1!row[Salary>1e9]` that matches no elements. The `MutationSelectorGuard.EnsureScoped` validation passes, but the handler returns `not_found` when the match set is empty.
- **Invalid selection state**: Using the `selected` pseudo-path (e.g., `set ... selected`) without an active watch server triggers `not_found` because the selection cannot be resolved.

### The invalid_value Error Code

The `invalid_value` code indicates that the supplied value cannot be parsed into the property's required type. Document handlers use property-specific validation methods to produce these errors:

- **Dimension parsing**: Values for coordinates (e.g., `x`, `y`, `width`) must be expressed as EMU, `cm`, `in`, `pt`, or `px`. Supplying `--prop x=foo` triggers `invalid_value` with the suggestion *"Use a number or unit (e.g. 2cm, 96px)"`.
- **Color formats**: The CLI accepts hex (`#FF0000`), named colors (`red`), RGB (`rgb(255,0,0)`), or theme tokens. Invalid strings like `--prop fill=blurple` return `invalid_value` with *"Supported color formats: #RRGGBB, red, rgb(r,g,b), accentN"*.
- **Enumerated properties**: Properties like `anchor` reject unsupported tokens (e.g., `middle` when only `center` or `top-left` are valid).
- **Numeric ranges**: Values exceeding bounds (e.g., `--prop opacity=1.5` when valid range is 0-1) trigger `invalid_value`.

## Where These Errors Originate in the Source Code

Error generation is distributed across three architectural layers in the `iOfficeAI/OfficeCLI` repository:

1. **CommandBuilder layer**: In [`src/officecli/CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs) (lines 66-80), the guard clause reports *"No properties to set..."* for missing required options. Lines 49-62 validate that you do not mix `--find` with `--prop find=...`, emitting `invalid_combination` errors.

2. **DocumentHandler layer**: Each handler ([`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), [`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.cs)) validates paths and values before applying changes. When a path cannot be resolved, the handler returns `not_found`; when validation fails, it returns `invalid_value`. The private `Validate` methods inside these handlers (e.g., `ValidateColor`, `ValidateDimension`, `ValidateEnum`) enforce schema compliance.

3. **OutputFormatter layer**: The `OutputFormatter.WrapEnvelopeError` method (called throughout [`CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Set.cs) lines 52-55 and [`CommandBuilder.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Add.cs)) wraps raw error data into the JSON envelope when `--json` is supplied, or prints colored messages otherwise.

## Common Scenarios and Fixes

### Resolving not_found Errors with Slide Indices

The most common `not_found` error occurs when assuming a document contains more elements than it actually does.

```bash

# Wrong: slide index exceeds document size

officecli set deck.pptx /slide[9] --prop title="Q4" --json

# Returns: {"error":{"code":"not_found","suggestion":"Valid Slide index range: 1-5"}}

```

**Fix:** Query the document structure first to determine valid paths.

```bash
officecli view deck.pptx outline --json | jq '.[] | .path'

# Returns: "/slide[1]" through "/slide[5]"

officecli set deck.pptx /slide[5] --prop title="Q4" --json

```

### Fixing invalid_value for Colors and Dimensions

Schema violations are immediately rejected with specific guidance.

```bash

# Wrong: invalid color name

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

# Returns: {"error":{"code":"invalid_value","suggestion":"Supported colors: #RRGGBB, red, rgb(r,g,b), accentN"}}

```

**Fix:** Use a supported format.

```bash
officecli set deck.pptx '/slide[1]/shape[1]' --prop fill=#FF8800 --json

```

### Avoiding invalid_combination Errors

The command accepts either `--find/--replace` flags **or** `--prop find=`/`replace=` syntax, but never both. Mixing them triggers an early error (see [`CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Set.cs) lines 49-62).

```bash

# Incorrect – both forms used

officecli set doc.docx /body/p[2] --find="TODO" --prop find=FIXME --json

# Returns: {"error":{"code":"invalid_combination","suggestion":"Use only --find or --prop find=…"}}

```

**Fix:** Maintain a single style.

```bash
officecli set doc.docx /body/p[2] --find="TODO" --replace="Done" --json

```

### Bulk-Setting Selected Elements

The `set selected` command expands the first selected path and applies properties to all additional selections (implemented in [`CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Set.cs) lines 98-121).

```bash

# In watch mode, select two shapes, then:

officecli set deck.pptx selected --prop fill=accent2 --json

```

If the watch server is not running, the command returns `not_found` with the advice to start `officecli watch …`.

## Diagnostic Workflow

Follow this systematic approach to resolve `set` and `add` failures:

1. **Add `--json`** to expose the full error envelope, making the code and suggestion fields visible.

   ```bash
   officecli set slide.pptx /slide[5] --prop x=foo --json
   ```

2. **Run `view … issues`** before mutation to list existing document problems that might affect path resolution.

   ```bash
   officecli view slide.pptx issues --json
   ```

3. **Consult built-in help** for the element type to see supported properties and value formats.

   ```bash
   officecli pptx set shape        # shows all shape properties

   officecli pptx set shape.x      # shows accepted units for x-coordinate

   ```

4. **Verify selection state** when using `selected` by checking if the watch server has an active selection.

   ```bash
   officecli get slide.pptx selected --json
   ```

   If this returns empty, the subsequent `set selected …` will emit `not_found`.

## Summary

- **`not_found`** indicates the DOM path does not exist (wrong index, empty selector, or no active selection), while **`invalid_value`** indicates the value fails schema validation (wrong type, format, or range).
- Errors originate in [`CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Set.cs), [`CommandBuilder.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Add.cs), and the specific `DocumentHandler` classes ([`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), [`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.cs)).
- Always use **`--json`** to expose the full error envelope with machine-readable codes and corrective suggestions.
- Validate paths first using `officecli view … outline` before attempting mutations on indexed elements like slides or rows.
- Never mix `--find` flags with `--prop find=...` syntax, as this triggers `invalid_combination` errors in the argument parser.

## Frequently Asked Questions

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

The `not_found` error code means the DocumentHandler could not resolve the DOM path you provided. This typically happens when you reference a slide index greater than the total slide count, use a selector that matches no elements (e.g., `row[Salary>1e9]`), or attempt to use the `selected` pseudo-path without an active `officecli watch` session. The error envelope includes a `suggestion` field showing valid ranges or available indices.

### Why does OfficeCLI reject my color values with invalid_value?

OfficeCLI enforces strict color schemas through the `ValidateColor` method in document handlers. The `invalid_value` code appears when you supply unsupported formats like arbitrary strings ("blurple") or malformed hex codes. Valid formats include hexadecimal (`#RRGGBB`), named colors (`red`, `blue`), RGB functions (`rgb(255,0,0)`), and theme tokens (`accent1`). Check the specific property help using `officecli <format> set <element>.<property>` to see accepted values.

### How do I fix invalid_value errors when setting shape dimensions?

Dimension properties (`x`, `y`, `width`, `height`) require numeric values with optional units. The `invalid_value` error occurs when you supply non-numeric strings or unsupported units. Valid units include EMU (raw), `cm`, `in`, `pt`, and `px`. For example, `--prop x=2cm` succeeds while `--prop x=2feet` fails. The error suggestion will list the valid unit abbreviations accepted by the specific handler.

### Can I use the selected pseudo-path without running officecli watch?

No. The `selected` pseudo-path requires an active watch server to maintain the selection state between the browser and the CLI. If you attempt `officecli set <file> selected --prop ...` without first running `officecli watch <file>`, the command returns `not_found` with a suggestion to start the watch server. Always verify the selection exists by running `officecli get <file> selected --json` before attempting mutations on selected elements.