# How to Debug Document Issues Using the OfficeCLI View Issues Command

> Debug document issues with OfficeCLI view issues command. Scan DOCX, PPTX, XLSX for problems. Get JSON output, filter types, and limit results for efficient troubleshooting.

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

---

**Use `officecli view <file> issues` to scan .docx, .pptx, and .xlsx files for structural, formatting, and content problems, with optional JSON output, type filtering, and result limiting.**

The `view issues` command in OfficeCLI is the primary diagnostic tool for identifying problems in Microsoft Office documents. Whether you're troubleshooting corrupted styles in a Word document, stale formula caches in Excel, or missing alt-text in PowerPoint, this command provides structured, machine-readable reports that integrate into CI/CD pipelines and manual debugging workflows.

## Command Structure and Entry Point

The `issues` mode originates in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), which handles all CLI request routing. When the mode string matches **issues** (lines 57‑60), the server invokes:

```csharp
OutputFormatter.FormatIssues(_handler.ViewAsIssues(issueType, limit), format)

```

This single call chains to format-specific handlers and wraps results in a standardized JSON envelope.

## How Document Scanning Works

Each file format implements its own `ViewAsIssues` method, tailored to the unique structures of .docx, .pptx, and .xlsx files.

### Word Documents (WordHandler.View.cs)

The Word implementation in [`src/officecli/Handlers/Word/WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.View.cs) (lines 1174‑1190) performs comprehensive style and content analysis:

- **Style integrity checks** – Detects duplicate style IDs, dangling references to non-existent styles, and circular style inheritance
- **Paragraph-level diagnostics** – Flags empty paragraphs, missing first-line indents, double spaces, and inconsistent formatting
- **Document structure validation** – Identifies broken content controls, tracked changes anomalies, and header/footer mismatches

The method returns a filtered `List<DocumentIssue>` based on the `--type` and `--limit` parameters.

### PowerPoint Presentations (PowerPointHandler.View.cs)

The PowerPoint handler focuses on slide-level and media issues:

- `slide_field_not_evaluated` – Unresolved field codes in placeholders
- Missing alt-text on images and charts
- Broken media references and external links
- Slide master/layout inconsistencies

### Excel Workbooks (ExcelHandler.View.cs)

The Excel scanner targets calculation and structural problems:

- `formula_cache_stale` – Cached values that don't match current formulas
- Cell overflow and data validation errors
- Broken external references and named range issues
- Shared formula inconsistencies

## Output Format and JSON Structure

All results pass through `OutputFormatter.FormatIssues` in [`src/officecli/Core/OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/OutputFormatter.cs) (lines 54‑63). The response envelope always sets `success: true` for probe commands, with issues arrayed in the `data` field:

```json
{
  "success": true,
  "data": [
    {
      "path": "/document/body/para[15]",
      "type": "Format",
      "severity": "warning",
      "message": "Empty paragraph with non-zero spacing"
    }
  ],
  "warnings": []
}

```

## Practical Usage Examples

### Basic Document Scan

List all detectable issues in a Word file:

```bash
officecli view report.docx issues

```

### Machine-Readable Output for Automation

Emit JSON for integration with build systems or analysis tools:

```bash
officecli view report.docx issues --json

```

### Filter by Issue Category

Show only structural problems (exclude formatting and content issues):

```bash
officecli view report.docx issues --type Structure --json

```

Available `--type` values: `Structure`, `Format`, `Content`.

### Limit Results for Large Files

Stop scanning after 20 issues to reduce processing time on massive documents:

```bash
officecli view report.docx issues --limit 20 --json

```

### Validation Chain

Combine with `validate` for pre-flight checks:

```bash
officecli validate report.docx && officecli view report.docx issues --json

```

## Debugging Workflow Integration

The `view issues` command works synergistically with other OfficeCLI operations:

1. **Locate** the problem using `view issues --json`
2. **Inspect** the specific content with `view text` or `view html`
3. **Fix** using `set`, `add`, or `remove` commands
4. **Verify** resolution by re-running `view issues`

The `Path` field in each issue provides an XPath-like locator compatible with OfficeCLI's mutation commands.

## Summary

- **Entry point:** [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) dispatches `issues` mode to `OutputFormatter.FormatIssues`
- **Format handlers:** [`WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.View.cs), [`PowerPointHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.View.cs), and [`ExcelHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.View.cs) implement `ViewAsIssues` with format-specific logic
- **Output:** Standardized JSON envelope via [`OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/OutputFormatter.cs) with `success: true` and issues in `data` array
- **Key flags:** `--json` for structured output, `--type` to filter by category, `--limit` to cap results
- **Integration:** Chain with `validate`, `view text/html`, and mutation commands for complete debugging workflows

## Frequently Asked Questions

### What file formats does the OfficeCLI view issues command support?

OfficeCLI supports **.docx**, **.pptx**, and **.xlsx** files through dedicated handlers. Each format has specialized issue detection: Word focuses on styles and paragraphs, PowerPoint on slides and media, and Excel on formulas and cell data.

### How do I extract only critical structural problems from a document?

Use the `--type Structure` flag to filter results. For JSON output suitable for automated processing: `officecli view file.docx issues --type Structure --json`. Structure issues include broken references, circular dependencies, and invalid document architecture.

### Can I process very large documents without scanning every issue?

Yes. The `--limit <N>` parameter stops scanning after N issues are found. This is essential for CI pipelines processing multi-megabyte files: `officecli view large.docx issues --limit 50 --json`.

### Where does the JSON output schema come from?

The schema is defined in [`OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/OutputFormatter.cs) lines 54‑63. All OfficeCLI commands use this unified envelope: top-level `success` boolean, `data` array containing command-specific results, and optional `warnings` array for non-fatal conditions.