iOfficeAI/OfficeCLI · error · CliException

unsupported_path

unsupported_path

Error message

dump path not supported: {path}. Supported: /, /SheetName, /sheet[N]

What it means

Thrown by ExcelBatchEmitter.EmitExcel when the dump path, after trimming slashes, is either empty (e.g. path was just "/") or contains additional '/' separators indicating a deeper path than supported. The emitter only supports single-level sheet paths — paths like '/Sheet1/Range' or '/a/b/c' are not valid dump targets. Note: path == '/' is handled separately before this check (it triggers a full-document dump), so this error fires only on paths that have content but are structurally unsupported.

Source

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

    /// 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);
    }

    private static void EmitWorkbookSettings(ExcelHandler xl, List<BatchItem> items,
        List<UnsupportedWarning> warnings)
    {
        DocumentNode wb;

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Use only sheet-level paths: '/SheetName' or '/sheet[N]'.
  2. Use '/' for the full document.
  3. For cell-level data, use the query/get commands instead of dump.
  4. Remove extra path segments — the emitter does not descend below the sheet level.

Example fix

// before: unsupported multi-segment path
ExcelBatchEmitter.EmitExcel(xl, "/Sheet1/A1:B2");

// after: dump the sheet, then query cells separately
var (items, warnings) = ExcelBatchEmitter.EmitExcel(xl, "/Sheet1");
Defensive patterns

Strategy: validation

Validate before calling

// Validate dump path structure before calling EmitExcel
static bool IsSupportedDumpPath(string path)
{
    if (string.IsNullOrEmpty(path) || path == "/") return true;
    var token = path.Trim('/');
    return token.Length > 0 && !token.Contains('/');
}

Type guard

static bool IsSupportedDumpPath(string path)
{
    if (string.IsNullOrEmpty(path) || path == "/") return true;
    var token = path.Trim('/');
    return !string.IsNullOrEmpty(token) && !token.Contains('/');
}

Try / catch

try
{
    var (items, warnings) = ExcelBatchEmitter.EmitExcel(xl, path);
}
catch (CliException ex) when (ex.Code == "unsupported_path")
{
    // Multi-segment or malformed path — use sheet-level only
    logger.LogError("Unsupported dump path '{Path}'. Use /, /SheetName, or /sheet[N].", path);
    throw;
}

Prevention

When it happens

Trigger: Passing a multi-segment path like '/Sheet1/A1:B2' (the emitter does not support cell-range dumps), passing '//' (trims to empty token), or passing '/Sheet1/' (the trailing slash is trimmed, leaving just 'Sheet1' which would actually be valid — so this specifically catches multi-segment or empty-after-trim paths).

Common situations: A user assuming cell-range or row-level dump paths are supported (they are not — only sheet-level); a path with extra slashes from string concatenation bugs; a path that was intended for a different command (e.g. a query path) mistakenly passed to the dump emitter.

Related errors

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