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

> Debug not_found errors in OfficeCLI by learning how to use --depth. This guide explains resolving not_found errors and offers expert suggestions for efficient debugging.

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

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```bash

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

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WatchNotifier.cs)), which serves as your starting point for constructing the corrected path.

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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WatchNotifier.cs) (lines 416-422) with message formatting in [`OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.