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

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 (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, ExcelHandler.cs, 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 lines 52-55 and 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.

# 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.

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.

# 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.

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 lines 49-62).

# 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.

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 lines 98-121).

# 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.

   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.

   officecli view slide.pptx issues --json

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

   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.

   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, CommandBuilder.Add.cs, and the specific DocumentHandler classes (WordHandler.cs, ExcelHandler.cs, 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.

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