# How to Debug Text Overflow and Formula Errors in OfficeCLI: A Complete Guide

> Debug OfficeCLI text overflow and formula errors. Run `officecli view <file> issues` to find problems and use `--format json` for programmatic inspection. Fix your documents quickly.

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

---

**Run `officecli view <file> issues` to surface all text-overflow warnings and formula parsing errors, then use `--format json` to inspect specific nodes programmatically.**

OfficeCLI provides built-in validation for every document-modifying command, catching **text overflow** (content exceeding container bounds) and **formula errors** (unparseable LaTeX expressions) before they corrupt your files. This guide explains how the iOfficeAI/OfficeCLI source code detects these problems and how you can diagnose and fix them using the CLI's native tooling.

## Understanding OfficeCLI's Debug Pipeline

OfficeCLI validates documents through a three-stage pipeline implemented across [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs), [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), and handler-specific files. Knowing this flow helps you interpret warning messages and choose the right debugging approach.

### Stage 1: Command Processing

Every command creates a `CommandBuilder` object that routes to the appropriate document handler (Word, Excel, PowerPoint). Handlers expose a uniform `IDocumentHandler` API supporting `Get`, `Set`, `Add`, `Delete`, and other operations.

### Stage 2: Overflow and Formula Validation

After mutations complete, two validation mechanisms activate:

- **Text overflow detection** — `CommandBuilder.CheckTextOverflow(IDocumentHandler, string)` walks the document tree, measures rendered text dimensions, and flags nodes exceeding their containers
- **Formula parsing** — `FormulaParser.ParseLenient` attempts strict LaTeX parsing; failures store raw strings for graceful degradation

### Stage 3: Error Reporting

Errors surface through dual channels:

- **stderr** — human-readable warnings like `WARNING: text_overflow`
- **JSON envelope** — machine-readable objects with `code` and `message` fields for programmatic handling

## Debugging Text Overflow Issues

Text overflow occurs when paragraphs, table cells, or shapes extend beyond page or slide boundaries. OfficeCLI detects this automatically after `set`, `add`, and `view` operations.

### Where Overflow Detection Lives

In [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) at line 1935, `CheckTextOverflow` computes rendered widths and heights using the layout engine:

- Returns warning strings for exceeded bounds
- Propagates JSON errors with code `"text_overflow"`
- Prints location paths like `/body[2]/p[5]` for precise node identification

PowerPoint shapes are checked via the same method in [`src/officecli/Handlers/Pptx/PowerPointHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.View.cs) at line 755.

### Command-Line Overflow Diagnostics

```bash

# List all overflow warnings for a document

officecli view mydoc.docx issues

```

Expected output:

```text
WARNING: text_overflow at /body[2]/p[5]
WARNING: text_overflow at /body[3]/table[1]/tr[2]/td[3]

```

### Fixing Overflow Problems

Reduce text volume or container constraints, then verify:

```bash

# Option 1: Reduce font size

officecli set mydoc.docx /body[2]/p[5] --prop size=9

# Option 2: Split content into multiple paragraphs

officecli add mydoc.docx /body[2]/p[6] --text "continued..."

# Verify fix

officecli view mydoc.docx issues

```

Repeat until warnings disappear.

## Debugging Formula Errors in Word Documents

Formula errors stem from malformed LaTeX that `FormulaParser.ParseLenient` cannot parse into an AST. OfficeCLI preserves your data by storing raw strings and surfacing errors during preview generation.

### Formula Parsing Architecture

| Component | Location | Function |
|-----------|----------|----------|
| Parser | [`WordHandler.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Add.cs#L1900) | `FormulaParser.ParseLenient` — strict parse with fallback |
| Setter validation | [`WordHandler.Set.Element.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.Element.cs#L803) | validates `formula` property on modifications |
| HTML renderer | [`WordHandler.HtmlPreview.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.HtmlPreview.cs#L610) | KaTeX rendering with error tooltips |

### Identifying Formula Problems

```bash

# Inspect a specific equation as JSON

officecli view mydoc.docx /body[1]/equation[3] --format json

```

Error response example:

```json
{
  "type": "error",
  "message": "Formula parsing failed: unexpected token"
}

```

The `type: "error"` node indicates `ParseLenient` failed and the raw LaTeX is preserved.

### Correcting Malformed Formulas

```bash

# Replace with valid LaTeX

officecli set mydoc.docx /body[1]/equation[3] --prop formula="E=mc^2"

```

The **resident autosave loop** ([`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs#L483) automatically sweeps the formula cache. Interrupted sweeps log retry messages and complete on the next idle window—no manual intervention required.

### HTML Preview for Visual Diagnosis

Generate a preview to see KaTeX rendering results:

```bash
officecli view mydoc.docx htmlpreview > preview.html

```

In the HTML:

- Successful formulas render as `<span class="katex-formula">` with proper typography
- Failed formulas display raw LaTeX with an error tooltip linking to [KaTeX supported syntax documentation](https://katex.org/docs/supported)

This visual feedback helps identify exactly which expressions need correction.

## Working with the Resident Server and Autosave Behavior

OfficeCLI's `ResidentServer` maintains document state and runs background validation. Understanding its behavior prevents confusion about when warnings appear or disappear.

### Formula Cache Sweep Mechanics

The autosave loop at [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs#L483):

1. Evaluates cached Excel (X-LSX) formulas
2. Retries interrupted sweeps on next idle window
3. Logs progress for transparency

If you see `formula_cache_sweep: retrying` in stderr, the server is handling concurrent commands safely—errors will resolve automatically.

### When Warnings Clear

| Scenario | Warning Persistence |
|----------|-------------------|
| Overflow fixed via `set` | Clears on next `view … issues` |
| Formula replaced via `set` | Clears after cache sweep completes |
| Preview generated | Reflects current state, no cache delay |

## Complete Debugging Workflow

Combine these commands for systematic issue resolution:

```bash

# 1. Discover all problems

officecli view mydoc.docx issues

# 2. Inspect specific error node

officecli view mydoc.docx /body[2]/p[5] --format json

# 3. Apply fix (example: reduce font)

officecli set mydoc.docx /body[2]/p[5] --prop size=9

# 4. Verify visually via HTML

officecli view mydoc.docx htmlpreview > preview.html
open preview.html

# 5. Confirm clean state

officecli view mydoc.docx issues

# (no output = no warnings)

```

## Key Source File Reference

| File | Purpose | Key Line |
|------|---------|----------|
| [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) | Overflow detection, error envelope creation | L1935 |
| [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) | Autosave loop, formula cache sweep | L483 |
| [`src/officecli/Handlers/Word/WordHandler.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.Add.cs) | Formula parsing with fallback | L1900 |
| [`src/officecli/Handlers/Word/WordHandler.Set.Element.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.Set.Element.cs) | Formula property validation | L803 |
| [`src/officecli/Handlers/Word/WordHandler.HtmlPreview.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.HtmlPreview.cs) | KaTeX rendering, error injection | L610 |
| [`src/officecli/Handlers/Pptx/PowerPointHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.View.cs) | Shape overflow checking | L755 |

## Summary

- **`officecli view <file> issues`** surfaces all text-overflow and formula errors via stderr and JSON
- **Text overflow** is detected by `CommandBuilder.CheckTextOverflow` which measures rendered dimensions and returns node paths like `/body[2]/p[5]`
- **Formula errors** occur when `FormulaParser.ParseLenient` fails; raw LaTeX is preserved and flagged in JSON nodes with `type: "error"`
- **Fixes** apply through standard `set` commands; the resident server's autosave loop automatically clears cached warnings
- **HTML previews** via `view … htmlpreview` provide visual confirmation with KaTeX rendering and graceful error display

## Frequently Asked Questions

### How do I see exactly which paragraph is overflowing?

Run `officecli view mydoc.docx issues` and read the path after `WARNING: text_overflow at`. Paths follow XPath-like syntax: `/body[2]/p[5]` means the fifth paragraph in the second document body section.

### Why does my formula warning persist after I fixed the LaTeX?

The resident server's formula cache sweep runs asynchronously. If the sweep was interrupted by a new command, it logs a retry message and completes on the next idle window. Run `officecli view mydoc.docx issues` again after a few seconds, or trigger a new operation to force a sweep.

### Can I suppress overflow warnings and force the change?

No. OfficeCLI validates mutations automatically and always reports overflow to prevent document corruption. You must reduce content size, increase container dimensions, or split content across multiple nodes.

### What's the difference between stderr warnings and JSON errors?

**Stderr warnings** appear as plain text for human readability during interactive use. **JSON errors** (from `--format json`) include structured `code` and `message` fields for programmatic processing in scripts and CI/CD pipelines.