How to Debug 'not_found' Errors with --depth in OfficeCLI: A Complete Guide

OfficeCLI returns a NotFound result when a selector cannot be resolved because the target element is not loaded at the current depth; resolving these errors requires incrementally increasing --depth, verifying parent containers with --json output, and re-indexing after structural modifications.

When working with the iOfficeAI/OfficeCLI repository to manipulate Office documents programmatically, encountering not_found errors is a common hurdle that indicates your query path exceeds the loaded node hierarchy. Understanding how to debug these errors using the --depth flag and the embedded suggestion system is essential for reliable document automation across Word, PowerPoint, and Excel files.

Understanding the NotFound Error Source

The NotFound error originates in src/officecli/Core/Watch/WatchNotifier.cs where the ScrollResult.NotFound factory method handles missing selectors (lines 416-422). When the CLI cannot locate an element, the OutputFormatter (lines 537-539) strips generic messages but preserves the NotFound payload for debugging, revealing the exact selector that failed and allowing you to copy-paste it into a corrected query.

How the --depth Parameter Controls Node Visibility

In src/officecli/CommandBuilder.GetQuery.cs (lines 17-34), the --depth option defines how many levels of child nodes the CLI expands when executing a get command. Line 34 specifically warns that deep nesting can break node-building, which directly correlates with not_found errors when selectors target unloaded descendants.

Step-by-Step Debugging Workflow

Verify the Parent Container First

Before increasing depth, confirm the parent element exists by querying it with --depth 1. If the parent itself returns NotFound, the issue lies higher in the hierarchy, not with your child selector.

officecli get "$FILE" "/body" --depth 1

Increase Depth Incrementally

Increase --depth values strategically (1, 2, 3) until the selector resolves. According to schemas/help/pptx/table.json (line 22), elements like table cells (/slide[N]/table[K]/row[R]/cell[C]) require at least --depth 2 to become addressable.

# Fails at depth 1

officecli get doc.pptx "/slide[3]/shape[2]" --depth 1

# Succeeds at depth 2

officecli get doc.pptx "/slide[3]/shape[2]" --depth 2

Inspect JSON Output for Structure

Append --json to receive structured output you can pipe into jq to examine child arrays and verify exact indices. This reveals whether elements are truly missing or merely indexed differently after structural changes.

officecli get doc.pptx "/slide[3]" --depth 1 --json | jq '.children'

Re-index After Structural Changes

After add or remove operations, immediately run get --depth 1 on affected containers. The NotFound message contains the failing selector (as implemented in WatchNotifier.cs), which serves as your starting point for constructing the corrected path.

officecli add doc.pptx "/slide" --type blank
officecli get doc.pptx "/slide" --depth 1  # identify new zero-based index

Common NotFound Scenarios and Solutions

• Zero-based vs One-based Indexing: Slides are zero-based in the CLI but one-based in the UI; after adding a slide, run get "/slide" --depth 1 to verify the actual index before referencing it in subsequent commands.
• Section Breaks Shifting Paragraphs: Adding a section inserts an empty paragraph, shifting all subsequent p[N] indices by +1; verify the updated structure with --depth 1 on /body.
• Table Cell Resolution Failures: Depth 1 only returns table and row stubs, not actual cells; use --depth 2 minimum or address cells via their full path (/slide[1]/table[1]/row[2]/cell[3]).

Code Examples for Debugging

# Debug a failing shape lookup

officecli get presentation.pptx "/slide[5]/shape[3]" --depth 1

# Returns: NotFound: selector not present

# Increase depth to load nested elements

officecli get presentation.pptx "/slide[5]/shape[3]" --depth 2

# Verify table structure before accessing cells

officecli get presentation.pptx "/slide[1]/table[1]" --depth 2 --json \
  | jq '.children[].children[].index'

# Fix index drift after insertion

officecli add document.docx "/body/p[5]" --type section
officecli get document.docx "/body" --depth 1 --json | jq '.children[].index'

Summary

• NotFound errors occur when selectors target nodes not loaded at the current --depth level
• Error handling is implemented in WatchNotifier.cs (lines 416-422) with message formatting in OutputFormatter.cs (lines 537-539)
• Always verify parent containers exist before debugging child selectors
• Increase --depth incrementally; complex elements like table cells require --depth 2 according to the PPTX schema
• Use --json output to inspect actual document structure and verify exact indices
• Re-index containers after add/remove operations to account for shifted positions and zero-based indexing

Frequently Asked Questions

Why does OfficeCLI return not_found even when the element exists in the document?

The CLI only loads child nodes up to the specified --depth. If your selector targets a nested element beyond that depth, the parser cannot resolve the path, triggering the ScrollResult.NotFound handler in WatchNotifier.cs. Increase the depth until the node becomes visible in the hierarchy.

What is the maximum --depth value I should use?

According to CommandBuilder.GetQuery.cs line 34, excessive depth can break node-building. Increase incrementally (1, 2, 3) only until the selector resolves; --depth 2 is typically sufficient for table cells and nested shapes, while --depth 3 handles deeply nested groups.

How do I find the correct index for a slide or paragraph after adding elements?

Run officecli get "$FILE" "/slide" --depth 1 or officecli get "$FILE" "/body" --depth 1 immediately after structural changes. The JSON output reveals the updated index array, accounting for zero-based CLI indexing versus one-based UI indexing shown in PowerPoint or Word.

Can I debug not_found errors without using the --json flag?

Yes, but --json provides structured visibility into the node hierarchy. Without it, you must increment --depth blindly and interpret text output. The JSON format (processed via jq) is the recommended method for debugging complex hierarchies because it shows the exact index values and children arrays referenced by the selector engine.

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