How to Debug Document Issues Using the OfficeCLI View Issues Command

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, which handles all CLI request routing. When the mode string matches issues (lines 57‑60), the server invokes:

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 (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 (lines 54‑63). The response envelope always sets success: true for probe commands, with issues arrayed in the data field:

{
  "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:

officecli view report.docx issues

Machine-Readable Output for Automation

Emit JSON for integration with build systems or analysis tools:

officecli view report.docx issues --json

Filter by Issue Category

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

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:

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

Validation Chain

Combine with validate for pre-flight checks:

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 dispatches issues mode to OutputFormatter.FormatIssues
• Format handlers: WordHandler.View.cs, PowerPointHandler.View.cs, and ExcelHandler.View.cs implement ViewAsIssues with format-specific logic
• Output: Standardized JSON envelope via 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 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.

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