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

> Debug document issues with OfficeCLI view issues. Scan Word, PowerPoint, and Excel for structural problems and use validate for XML schema compliance. Fix files fast.

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

---

**Use the `officecli view <file> issues` command to scan Word, PowerPoint, and Excel documents for structural problems, and combine it with `officecli validate` to verify XML schema compliance before delivery.**

OfficeCLI is an open-source command-line tool from the iOfficeAI/OfficeCLI repository that diagnoses and repairs Office documents. When you need to debug document issues using the OfficeCLI view issues command, you gain access to deep structural analysis for Word (.docx), PowerPoint (.pptx), and Excel (.xlsx) files. This tool inspects document internals beyond what typical Office applications reveal, identifying problems like duplicate IDs, dangling references, and schema violations.

## Understanding the OfficeCLI View Issues Command

The `view issues` command operates as a diagnostic scanner that returns a list of **DocumentIssue** objects specific to each Office format. Unlike simple error checking, this command performs handler-specific scans that understand the unique architecture of each document type.

### Word Document Issue Detection in WordHandler.View.cs

For Word documents, the scan logic resides in [`src/officecli/Handlers/Word/WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.View.cs). This handler populates a `List<DocumentIssue>` with structural problems including duplicate IDs, dangling references, and style-index mismatches. These issues often remain hidden until documents are processed programmatically or opened in strict compliance modes.

### PowerPoint and Excel Issue Detection

PowerPoint diagnostics are implemented in [`src/officecli/Handlers/Pptx/PowerPointHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.View.cs), which checks for slide-level issues, malformed shapes, and missing resources. For Excel workbooks, [`src/officecli/Handlers/Excel/ExcelHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Excel/ExcelHandler.View.cs) detects formula-cache stalls, overflowed cells, and stale references that could cause calculation errors or corruption warnings.

## Validating XML Schema with the Validate Command

While `view issues` detects logical and structural problems, the `validate` command performs OpenXML SDK schema validation to catch XML-level errors. According to the source code in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs), this command sets a non-zero exit code when schema violations are detected, making it ideal for CI/CD pipelines. Validation is also invoked implicitly after batch mutations to guarantee schema compliance.

## Step-by-Step Debugging Workflow

Follow this systematic approach to diagnose and resolve document problems:

1. **Run `view issues`** – Execute `officecli view <file> issues` to identify high-level structural problems like duplicate IDs or missing resources.
2. **Run `validate`** – Execute `officecli validate <file>` to confirm the document passes XML schema validation.
3. **Iterate repairs** – Use OfficeCLI commands like `set`, `add`, or `remove` to fix reported issues, then repeat steps 1-2 until both commands report clean states.
4. **Visual verification** – For PowerPoint decks, optionally run `view screenshot` to catch layout problems not visible in textual issue reports.

As documented in [`src/officecli/McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/McpServer.cs), this sequence forms part of the "delivery gate" that requires both `view issues` and `validate` to be clean before a document is considered ready for delivery.

## Practical Code Examples

Use these commands to integrate OfficeCLI debugging into your workflow:

```bash

# Display all structural issues in a Word document

officecli view report.docx issues

# Export issues to JSON for automated processing

officecli view report.docx issues --json > issues.json

# Validate XML schema compliance with error exit codes

officecli validate report.docx

# CI pipeline integration example

if ! officecli validate report.docx; then
  echo "Schema validation failed"
  exit 1
fi

if officecli view report.docx issues --json | jq '.[] | select(.type=="error")'; then
  echo "Document issues detected"
  exit 1
fi

echo "Document passed both checks"

```

## Summary

- The `officecli view issues` command scans documents for format-specific structural problems via dedicated handlers in [`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).
- The `validate` command performs OpenXML SDK schema validation and returns non-zero exit codes for failures, as implemented in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs).
- Both commands support `--json` output for machine-readable integration and form the "delivery gate" documented in [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) to ensure production-ready documents.
- Combining both commands creates a robust debugging workflow for Word, PowerPoint, and Excel files.

## Frequently Asked Questions

### What types of issues does OfficeCLI view issues detect?

The command detects format-specific structural problems: Word documents are checked for duplicate IDs, dangling references, and style-index mismatches; PowerPoint files are scanned for slide-level issues, malformed shapes, and missing resources; Excel workbooks are analyzed for formula-cache stalls, overflowed cells, and stale references.

### How do I export OfficeCLI issue reports to JSON?

Append the `--json` flag to either the `view issues` or `validate` commands. For example, `officecli view document.docx issues --json` outputs a structured JSON array of DocumentIssue objects suitable for piping into tools like `jq` or for automated CI/CD processing.

### What is the difference between view issues and validate in OfficeCLI?

`view issues` performs semantic analysis of document structure using format-specific handlers to find logical problems like broken references, while `validate` uses the OpenXML SDK to verify XML schema compliance. The former catches content logic errors; the latter catches markup syntax violations. Both are required for the delivery gate documented in [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs).

### How does OfficeCLI handle exit codes for validation failures?

According to [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), the `validate` command returns a non-zero exit code when schema errors are detected, enabling reliable error handling in shell scripts and CI pipelines. The `view issues` command similarly indicates problem severity through its output, though explicit exit code behavior for issues should be checked against your specific OfficeCLI version.