-
Notifications
You must be signed in to change notification settings - Fork 102
troubleshooting
Common errors and solutions for OfficeCLI.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
Cause: The resident process may have crashed or timed out (12 min idle timeout).
Solution: Just run commands directly -- they auto-fallback to non-resident mode. Or use officecli open file to restart the resident process.
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.
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.
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.
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.
- Use
view outlineto understand the document structure - Use
get / --depth 2to explore paths - Use
queryto find elements - Use
validateafter modifications - Use
rawto inspect XML when high-level commands don't explain the issue
- Always
getbeforesetto verify the path exists - Use
--jsonfor programmatic parsing — all commands return a{ "success": true/false, ... }envelope - On error with
--json, checkerror.codeanderror.suggestionfor machine-readable details - Use batch mode for multiple changes (atomic, faster)
- Use resident mode for interactive workflows
- Path indices are 1-based,
--indexparameter is 0-based - Colors are hex without
#:FF0000not#FF0000 - Dimensions accept unit suffixes:
2cm,1in,12pt - Image
path/srcaccepts local files,data:image/...;base64,...data URIs, orhttps://...URLs - Use
officecli mcp <target>to register as MCP server in AI clients
Based on OfficeCLI v1.0.28