iOfficeAI/OfficeCLI · error · ArgumentException

Sheet not found: {ptSheetName}

Error message

Sheet not found: {ptSheetName}

What it means

Thrown by AddPivotTable when the first segment of the parent path (the sheet that will host the pivot) does not resolve via FindWorksheet. A pivot table must be anchored to a concrete worksheet, so an unknown host sheet name is rejected up front rather than producing an orphan pivot cache.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Tables.cs:1661

        {
            tableParts = new TableParts();
            tblWs.AppendChild(tableParts);
        }
        tableParts.AppendChild(new TablePart { Id = tblWorksheet.GetIdOfPart(tableDefPart) });
        tableParts.Count = (uint)tableParts.Elements<TablePart>().Count();
        SaveWorksheet(tblWorksheet);

        var tblIdx = PathIndex.FromArrayIndex(tblWorksheet.TableDefinitionParts.ToList().IndexOf(tableDefPart));
        return $"/{tblSheetName}/table[{tblIdx}]";
    }

    private string AddPivotTable(string parentPath, string type, InsertPosition? position, Dictionary<string, string> properties)
    {
        var index = position?.Index;
        var ptSegments = parentPath.TrimStart('/').Split('/', 2);
        var ptSheetName = ptSegments[0];
        var ptWorksheet = FindWorksheet(ptSheetName)
            ?? throw new ArgumentException($"Sheet not found: {ptSheetName}");

        // Source: "Sheet1!A1:D100" or "A1:D100" (same sheet)
        var sourceSpec = properties.GetValueOrDefault("source", "")
            ?? properties.GetValueOrDefault("src", "")
            ?? throw new ArgumentException("pivottable requires 'source' property (e.g. source=Sheet1!A1:D100)");
        if (string.IsNullOrEmpty(sourceSpec))
            throw new ArgumentException("pivottable requires 'source' property (e.g. source=Sheet1!A1:D100)");

        // R8-7: incidental whitespace around the source spec or its
        // components (" Sheet1 ! A1:D10 ") is a common paste-from-docs
        // artefact. Trim the whole string and both sides of the '!'
        // split so the downstream sheet/range lookup sees clean values.
        sourceSpec = sourceSpec.Trim();

        // R8-3: external workbook refs such as [other.xlsx]Sheet1!A1:D10
        // used to fall through to FindWorksheet and surface as the
        // misleading "Source sheet not found: [other.xlsx]Sheet1".
        // Detect the '[' prefix up front and throw a clear error so

View on GitHub (pinned to 1ced45e900)

Solutions

1. Verify the host sheet exists by listing the workbook's sheets.
2. Quote sheet names with spaces exactly as stored.
3. Create the host sheet first with --type sheet if it does not exist.

Example fix

// before
add /Report/pivottable --prop source=Data!A1:D100
// after (create host sheet first)
add /sheet --prop name=Report
add /Report/pivottable --prop source=Data!A1:D100

// Confirm the host sheet exists before adding a pivot table to it.
var sheetName = parentPath.TrimStart('/').Split('/', 2)[0];
if (handler.FindWorksheet(sheetName) is null)
    throw new InvalidOperationException($"Cannot add pivot: host sheet '{sheetName}' not found.");

try { handler.Add(parentPath, "pivottable", null, props); }
catch (ArgumentException ex) when (ex.Message.StartsWith("Sheet not found"))
{ /* list sheets; create the host sheet if needed, then retry */ }

When it happens

Trigger: Calling Add('/MissingSheet/pivottable', ...) where no worksheet named MissingSheet exists, including case, whitespace, or renamed-sheet mismatches.

Common situations: Sheet was deleted/renamed, name with spaces unquoted, or using a sheet index where a name is required.

Related errors

• Source sheet not found: {sourceSheetName}
• Pivot name '{explicitName}' already exists in workbook
• Property 'sqref' (or 'range'/'ref') is required for validati
• Sheet not found: {tblSheetName}
• pivottable requires 'source' property (e.g. source=Sheet1!A1

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