iOfficeAI/OfficeCLI · error · CliException

invalid_format

invalid_format

Error message

Unsupported --format: {format}. Valid: batch

What it means

Thrown by the `dump` command when --format is anything other than `batch` (case-insensitive). dump currently serializes only to the replayable batch format; the guard at line 46-48 rejects other values with code `invalid_format` and a ValidValues list of `['batch']`.

Source

Thrown at src/officecli/CommandBuilder.Dump.cs:47

        };
        var outOpt = new Option<string?>("--out", "-o") { Description = "Write output to a file instead of stdout" };

        var dumpCommand = new Command("dump", "Serialize a document subtree into a replayable batch script (round-trip mechanism)");
        dumpCommand.Add(dumpFileArg);
        dumpCommand.Add(dumpPathArg);
        dumpCommand.Add(formatOpt);
        dumpCommand.Add(outOpt);
        dumpCommand.Add(jsonOption);

        dumpCommand.SetAction(result => { var json = result.GetValue(jsonOption); return SafeRun(() =>
        {
            var file = result.GetValue(dumpFileArg)!;
            var path = OfficeCli.Core.MsysPathHint.Restore(result.GetValue(dumpPathArg)) ?? "/";
            var format = (result.GetValue(formatOpt) ?? "batch").ToLowerInvariant();
            var outPath = result.GetValue(outOpt);

            if (format != "batch")
                throw new CliException($"Unsupported --format: {format}. Valid: batch")
                    { Code = "invalid_format", ValidValues = ["batch"] };

            var ext = Path.GetExtension(file.FullName).ToLowerInvariant();
            if (ext != ".docx" && ext != ".pptx" && ext != ".xlsx")
                throw new CliException($"dump currently supports .docx, .pptx and .xlsx (got {ext})")
                    { Code = "unsupported_format" };

            // CONSISTENCY(file-not-found): mirror the get/set/query format —
            // "File not found: <path>. Use 'officecli create <path>' to create a
            // blank document, or check the file extension.". Without this
            // early guard the dump path falls through to the SDK opener whose
            // raw '.NET Could not find file' message disagrees with every
            // other command and skips the actionable suggestion.
            if (!File.Exists(file.FullName))
                throw new CliException(
                    $"File not found: {file.FullName}. " +
                    $"Use 'officecli create {file.FullName}' to create a blank document, " +
                    $"or check the file extension.")

View on GitHub (pinned to 1ced45e900)

Solutions

1. Drop --format (defaults to batch) or pass `--format batch` explicitly.
2. For JSON output of the document tree use `get --json` or `query --json` instead of dump.
3. Watch release notes — additional formats may be added later.

Example fix

# before
officecli dump file.docx / --format json

# after
officecli dump file.docx / --format batch
# or simply
officecli dump file.docx /

// Only allow the supported dump format.
var fmt = (format ?? "batch").ToLowerInvariant();
if (fmt != "batch") throw new ArgumentException("dump --format only accepts 'batch'");

// Guard: format is supported by dump.
static bool DumpFormatSupported(string? f) =>
    (f ?? "batch").ToLowerInvariant() == "batch";

When it happens

Trigger: `officecli dump file.docx / --format json`, `--format xml`, `--format csv`, etc. format.ToLowerInvariant() != "batch" triggers the throw.

Common situations: User assumes dump supports json/xml like query/get do; a script passes a generic --format from a shared options object; an agent guesses a format value.

Related errors

• invalid_value
• Anchor must be a row path like /{sheetName}/row[K], got: {an
• ${r.stderr || r.stdout}
• invalid_argument
• missing_argument

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/fb0b8f3ed456366c. Report an issue: GitHub.