# How to Debug Document Issues Using OfficeCLI: `view issues` and `validate` Commands

> Debug document issues with OfficeCLI. Use view issues to find structural problems and validate to check XML schema compliance for a complete health check on your documents.

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

---

**Use `officecli view <file> issues` to scan for structural problems and `officecli validate <file>` to check XML schema compliance, combining both for a complete document health check.**

OfficeCLI (iOfficeAI/OfficeCLI) is an open-source command-line tool for diagnosing and repairing Word, PowerPoint, and Excel documents. When you need to debug document issues using OfficeCLI, the `view issues` and `validate` commands provide a two-layer defense: semantic structural scanning and strict XML schema validation. These commands work across `.docx`, `.pptx`, and `.xlsx` formats to catch errors before they reach production.

## How `view issues` Scans Document Structure

The `view issues` command operates as a structural analyzer that returns a list of **DocumentIssue** objects specific to each Office format. Unlike simple XML validation, this scans for semantic problems like duplicate IDs, dangling references, and content inconsistencies that survive manual editing but break automation workflows.

### Word Document Issue Detection

In [`src/officecli/Handlers/Word/WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.View.cs), the Word handler populates a `List<DocumentIssue>` with problems such as **duplicate IDs**, **dangling references**, and **style-index mismatches**. These issues often originate from copy-paste operations or template merging and can cause rendering inconsistencies across different versions of Microsoft Word.

### PowerPoint Issue Detection

The PowerPoint handler in [`src/officecli/Handlers/Pptx/PowerPointHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.View.cs) checks for slide-level issues, **malformed shapes**, and **missing resources**. This catches broken image links, corrupted slide layouts, and shape references that point to deleted objects—problems that cause "repair" dialogs when opening presentations.

### Excel Issue Detection

Excel scanning lives in [`src/officecli/Handlers/Excel/ExcelHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Excel/ExcelHandler.View.cs), where the tool identifies **formula-cache stalls**, **overflowed cells**, and **stale references**. These structural defects often trigger calculation errors or file corruption warnings when the spreadsheet is opened in Excel.

### Output Formats and JSON Support

Results display in human-readable text by default. Add the `--json` flag to emit structured JSON for integration with CI/CD pipelines or automated reporting systems.

## How `validate` Checks XML Schema Compliance

The `validate` command runs the OpenXML SDK's strict schema validation against the document package. In [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs), the request dispatcher recognizes the validation verb and sets a **non-zero exit code** when schema errors are found. This command validates that the document adheres to the Office Open XML specification, catching malformed XML that might cause compatibility issues or refusal to open in strict-mode applications.

## Step-by-Step Debugging Workflow

Follow this systematic approach to debug document issues using OfficeCLI before delivery:

1. **Run `view issues`** – Identify high-level structural problems like duplicate IDs or missing resources.
2. **Run `validate`** – Confirm the document passes XML schema validation.
3. **Iterate** – Use `set`, `add`, or `remove` commands to fix reported issues, then repeat steps 1-2 until both commands report clean states.
4. **Visual audit** – For PowerPoint decks, run `view screenshot` to catch layout problems not visible in text-based issue reports.

According to [`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 commands to return clean results before a document is considered ready for publishing.

## Practical Examples and CI Integration

Here's how to integrate these commands into your debugging workflow:

```bash

# Show structural issues in a Word document

officecli view report.docx issues

# Export issues as JSON for automated processing

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

# Validate XML schema with exit code support

officecli validate report.docx

# Combined CI pipeline check

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

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

echo "Document passed both checks"

```

## Summary

- **`view issues`** scans for structural defects like duplicate IDs, dangling references, and malformed shapes, implemented separately for Word, PowerPoint, and Excel in their respective [`Handler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Handler.View.cs) files.
- **`validate`** performs OpenXML SDK schema validation via [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs), returning non-zero exit codes on failure.
- Both commands support `--json` output for machine-readable integration with CI/CD systems.
- The debugging workflow documented in [`src/officecli/McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/McpServer.cs) requires both checks to pass the "delivery gate" before document delivery.
- These commands support `.docx`, `.pptx`, and `.xlsx` formats.

## Frequently Asked Questions

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

`view issues` performs a semantic scan for structural problems like duplicate IDs, missing resources, and style inconsistencies specific to each Office format. `validate` runs the OpenXML SDK's XML schema validation to ensure the document conforms to the Office Open XML specification. Use `view issues` to catch content logic errors and `validate` to catch malformed XML.

### How do I automate OfficeCLI document checks in a CI/CD pipeline?

Add the `--json` flag to both commands for machine-readable output, then check exit codes. `validate` returns non-zero on schema errors, while `view issues` requires parsing JSON to detect error-level entries. Pipe the JSON output to tools like `jq` to filter for specific issue types and fail the build when defects are found.

### Which file handles the validation logic and exit code setting?

The `validate` command logic resides in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs), where the request dispatcher processes the validation verb and sets non-zero exit codes when schema errors are detected. This ensures your scripts can reliably detect validation failures.

### Can OfficeCLI detect PowerPoint layout issues that aren't XML errors?

Yes. While `validate` catches XML schema violations, `view issues` detects higher-level problems like malformed shapes and missing resources in [`src/officecli/Handlers/Pptx/PowerPointHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.View.cs). For visual layout verification, use the `view screenshot` command to render the deck and inspect slide appearance manually.