iOfficeAI/OfficeCLI · error · CliException

invalid_path

invalid_path

Error message

dump path cannot be empty. Use '/' for the full document or a sheet path like /Sheet1. Supported: /, /SheetName, /sheet[N]

What it means

Thrown by ExcelBatchEmitter.EmitExcel when the dump path argument is null or empty. The emitter supports three path forms: '/' (full document), '/SheetName' (single sheet), and '/sheet[N]' (sheet by 1-based index). An empty path is rejected explicitly rather than falling through, because it would be ambiguous — the caller likely forgot to specify which subtree to dump. The SupportedHint constant lists all valid forms in the message.

Source

Thrown at src/officecli/Handlers/Excel/ExcelBatchEmitter.cs:182

        EmitDocPropsScan(xl, warnings);

        return (items, warnings);
    }

    /// <summary>
    /// Emit a subtree. Supported paths: `/` (full document), `/SheetName`,
    /// `/sheet[N]`. A single-sheet dump emits `add sheet` (not the
    /// rename-first-sheet form) so it can replay onto a workbook that
    /// already has content; workbook-level settings and named ranges are
    /// NOT included (they live at sibling paths — mirrors the docx/pptx
    /// subtree contract).
    /// </summary>
    public static (List<BatchItem> Items, List<UnsupportedWarning> Warnings) EmitExcel(
        ExcelHandler xl, string path)
    {
        const string SupportedHint = "Supported: /, /SheetName, /sheet[N]";
        if (string.IsNullOrEmpty(path))
            throw new CliException($"dump path cannot be empty. Use '/' for the full document or a sheet path like /Sheet1. {SupportedHint}")
                { Code = "invalid_path" };
        if (path == "/") return EmitExcel(xl);

        var token = path.Trim('/');
        if (token.Length == 0 || token.Contains('/'))
            throw new CliException($"dump path not supported: {path}. {SupportedHint}")
                { Code = "unsupported_path" };

        var sheetName = xl.ResolveDumpSheetName(token)
            ?? throw new CliException($"dump path not found: {path} (no such sheet)")
                { Code = "path_not_found" };

        var items = new List<BatchItem>();
        var warnings = new List<UnsupportedWarning>();
        EmitSheet(xl, sheetName, renameFirstSheet: false, items, warnings, claimExistingSheet: true);
        EmitPivotTables(xl, "/" + sheetName, xl.GetDumpPivotCount(sheetName), items, warnings);
        EmitSlicers(xl, "/" + sheetName, xl.GetDumpSlicerCount(sheetName), items, warnings);
        return (items, warnings);

View on GitHub (pinned to 1ced45e900)

Solutions

Pass '/' explicitly to dump the full document.
Pass '/SheetName' (e.g. '/Sheet1') to dump a specific sheet by name.
Pass '/sheet[N]' (e.g. '/sheet[0]') to dump a sheet by 0-based index.
If the path is computed dynamically, add a fallback: string.IsNullOrEmpty(path) ? "/" : path.

Example fix

// before: empty path
var (items, warnings) = ExcelBatchEmitter.EmitExcel(xl, "");

// after: full document dump
var (items, warnings) = ExcelBatchEmitter.EmitExcel(xl, "/");

Defensive patterns

Strategy: validation

Validate before calling

// Validate dump path before calling EmitExcel
static string NormalizeDumpPath(string? path) => string.IsNullOrEmpty(path) ? "/" : path;
var (items, warnings) = ExcelBatchEmitter.EmitExcel(xl, NormalizeDumpPath(dumpPath));

Type guard

static bool IsValidDumpPath(string? path) =>
    !string.IsNullOrEmpty(path) && (path == "/" || !string.IsNullOrEmpty(path.Trim('/')));

Try / catch

try
{
    var (items, warnings) = ExcelBatchEmitter.EmitExcel(xl, path);
}
catch (CliException ex) when (ex.Code == "invalid_path")
{
    // Empty path — default to full document dump
    var (items, warnings) = ExcelBatchEmitter.EmitExcel(xl, "/");
}

Prevention

Always pass an explicit path: '/' for the full document, '/SheetName' for a single sheet.
If the path is computed dynamically, provide '/' as the default fallback.
Validate the path is non-empty before calling the emitter.

When it happens

Trigger: Calling EmitExcel(xl, "") or EmitExcel(xl, null) — the dump path argument was not provided or was passed as an empty string. This typically happens when a caller computes the path dynamically and the computation yields empty, or when the '/' default was expected but not explicitly passed.

Common situations: A dump command invoked without a path argument; a script that builds the path conditionally and hits a branch where the variable is empty; a programmatic caller that assumed '/' was the default when it is not.

Related errors

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