troubleshooting

Troubleshooting

Common errors and solutions for OfficeCLI.

---

Common Errors

"Sheet not found: {name}"

Cause: Sheet name doesn't match exactly. Sheet names are case-sensitive. Solution: Use officecli get file.xlsx / to list actual sheet names, then use the exact name shown.

"Element not found at path: {path}"

Cause: The specified path doesn't exist in the document. Solution: Use officecli get file /path --depth 2 to explore available children. Remember that indices are 1-based (e.g., /Sheet1/row[1] is the first row).

"Unsupported property: {key} (valid props: ...)"

Cause: The property is not supported for this element type. Solution: The error message now includes a list of valid properties for the element. Use the suggested property names directly. Property keys are case-insensitive. For the full property reference, check the element's -set or -add wiki page.

"Either --type or --from must be specified"

Cause: The add command requires a --type flag to know what kind of element to create. Solution: Add --type <element-type> to your command, or use --from <file> to add from an existing source.

"File is held by resident process"

Cause: Trying to create or overwrite a file that has an active resident process. Solution: Use officecli close file first to release the file, then retry your command.

Edit reports success but a third-party tool reads the old file

Cause: A resident process is keeping the document in memory. Mutations (set/add/remove/batch) are applied in memory and reported as success, but the file on disk is only refreshed on a flush — the idle auto-save (adaptive 2–10s), save, close, or idle shutdown. OfficeCLI commands read the in-memory copy (so they show the change), but a tool that opens the file directly — python-docx, PizZip, openpyxl, pandas, Microsoft Word — reads the unflushed disk file. The change is not lost; it is held in the resident. Solution: If the read can wait a couple of seconds, the idle auto-save flushes for you (adaptive 2–10s after the last command). To make it immediate, run officecli save <file> after your edits (keeps the resident running so further edits stay fast) — or officecli close <file> when you are completely done (flush + release). For a workflow where another program reads after every command, set OFFICECLI_RESIDENT_FLUSH=each — every mutation is flushed before its command returns while the resident (and its speed) is kept; OFFICECLI_NO_AUTO_RESIDENT=1 achieves the same guarantee but re-opens the file per command, which is much slower on large documents. See save and open / close → When the file on disk is refreshed.

"Named range '{name}' not found"

Cause: The named range doesn't exist in the workbook. Solution: Use officecli get file.xlsx / and check the namedrange entries to see available named ranges.

"Validation index out of range"

Cause: The validation index you specified doesn't exist. Solution: Use officecli get file.xlsx /SheetName to see how many validations exist before referencing by index.

"Table index out of range"

Cause: The table index you specified doesn't exist. Solution: Use officecli get file.xlsx /SheetName to see how many tables exist before referencing by index.

Document opens but looks wrong after modification

Cause: Usually a validation error in the document structure. Solution: Run officecli validate file to check for issues. Common causes include invalid XML in raw-set or wrong property values.

"Picture/image file not found"

Cause: The file path is relative to where officecli is run, not relative to the document. Solution: Use absolute paths for image files, or ensure your working directory is correct.

Resident process not responding

Cause: The resident process may have crashed or timed out (idle timeout: 60s when auto-started, 12 min after an explicit open). Solution: Just run commands directly -- they auto-fallback to non-resident mode. Or use officecli open file to restart the resident process.

"No data validations found in sheet"

Cause: Trying to set or get validation[N] but no validations exist in the sheet. Solution: Add a validation first before trying to reference one by index.

Batch command partially failed

Cause: By default, batch mode continues on error. Solution: Check output for [N] ERROR: lines to identify which commands failed. Use --stop-on-error to halt on the first failure.

Numbers showing as text in Excel

Cause: Cell values are stored as text instead of numbers. Solution: Set --prop type=number or ensure the value is numeric. Check the current type with officecli get file.xlsx /Sheet1/A1.

Merge cells not working

Cause: Using a single cell path instead of a range path. Solution: Use a range path: officecli set file.xlsx /Sheet1/A1:D1 --prop merge=true, not a single cell path.

---

General Debugging Steps

1. Use view outline to understand the document structure
2. Use get / --depth 2 to explore paths
3. Use query to find elements
4. Use validate after modifications
5. Use raw to inspect XML when high-level commands don't explain the issue

---

Tips

• Always get before set to verify the path exists
• Use --json for programmatic parsing — all commands return a { "success": true/false, ... } envelope
• On error with --json, check error.code and error.suggestion for machine-readable details
• Use batch mode for multiple changes (one pass, faster; continues on error by default — not atomic)
• Use resident mode for interactive workflows
• Path indices are 1-based, --index parameter is 0-based
• Colors are hex without #: FF0000 not #FF0000
• Dimensions accept unit suffixes: 2cm, 1in, 12pt
• Image path/src accepts local files, data:image/...;base64,... data URIs, or https://... URLs
• Use officecli mcp <target> to register as MCP server in AI clients

---

Based on OfficeCLI v1.0.64