iOfficeAI/OfficeCLI · error · InvalidOperationException

Pivot cache definition is missing

Error message

Pivot cache definition is missing

What it means

The cache definition part exists but its PivotCacheDefinition root element is null — the part is present but empty or has an unrecognised/unloaded root. This is a structural corruption detectable only at runtime; the helper cannot proceed because every subsequent operation (CacheSource, WorksheetSource, CacheFields) hangs off the cache definition element.

Source

Thrown at src/officecli/Core/PivotTableHelper.Readback.cs:382

    /// resizes pivotDef.PivotFields to match the new column count. Existing
    /// PivotField Axis/DataField assignments are reset because indices may no
    /// longer line up — RebuildFieldAreas reapplies them after this returns.
    /// </summary>
    private static void RefreshPivotCacheFromSource(PivotTablePart pivotPart, string newSourceSpec,
        Dictionary<string, string>? pendingFieldAreaProps = null)
    {
        if (string.IsNullOrWhiteSpace(newSourceSpec))
            throw new ArgumentException("source must not be empty");
        newSourceSpec = newSourceSpec.Trim();
        if (newSourceSpec.StartsWith("["))
            throw new ArgumentException(
                "External workbook references are not supported in pivot source. "
                + "Use a local sheet name (e.g. Sheet1!A1:D10)");

        var cachePart = pivotPart.GetPartsOfType<PivotTableCacheDefinitionPart>().FirstOrDefault()
            ?? throw new InvalidOperationException("Pivot table has no cache definition part");
        var cacheDef = cachePart.PivotCacheDefinition
            ?? throw new InvalidOperationException("Pivot cache definition is missing");
        var existingWsSource = cacheDef.CacheSource?.WorksheetSource
            ?? throw new InvalidOperationException("Pivot cache source is not a worksheet source");

        // Parse the new source spec.
        string newSheetName;
        string newRef;
        if (newSourceSpec.Contains('!'))
        {
            var parts = newSourceSpec.Split('!', 2);
            newSheetName = parts[0].Trim().Trim('\'', '"').Trim();
            newRef = parts[1].Trim();
        }
        else
        {
            newSheetName = existingWsSource.Sheet?.Value ?? "";
            newRef = newSourceSpec;
        }

View on GitHub (pinned to 1ced45e900)

Solutions

1. Restore from a known-good copy of the file
2. Recreate the pivot from scratch so a fresh, well-formed cache definition is generated
3. Inspect the part's XML directly (rename to .zip and open pivotCacheDefinition1.xml) to confirm it has a <pivotCacheDefinition> root

var cachePart = pivotPart.GetPartsOfType<PivotTableCacheDefinitionPart>().FirstOrDefault();
if (cachePart?.PivotCacheDefinition == null)
    throw new InvalidOperationException("Cache definition part is missing its root element");

static bool HasCacheDefinitionRoot(PivotTablePart p)
{
    var cp = p.GetPartsOfType<PivotTableCacheDefinitionPart>().FirstOrDefault();
    return cp?.PivotCacheDefinition != null;
}

try { RefreshPivotCacheFromSource(pivotPart, sourceSpec); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Pivot cache definition is missing"))
{ /* restore from backup or recreate the pivot */ }

When it happens

Trigger: The cache definition XML was deleted but the part and relationship remain; the root element is in a namespace the SDK did not bind; the part stream is empty or contains malformed XML that the SDK silently left unloaded.

Common situations: Truncated file; partial write by a crashing producer; namespace or schema-version mismatch with the loaded OpenXML SDK; hand-edited package where the cache definition content was emptied.

Related errors

• Pivot table has no cache definition part
• Workbook part not reachable from pivot table part
• Pivot cache source is not a worksheet source
• source must not be empty
• External workbook references are not supported in pivot sour

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