qax-os/excelize · error

unsupported pivot table cache source type: %s

Error message

unsupported pivot table cache source type: %s

What it means

Excelize supports pivot caches built from worksheet ranges; this error is thrown when a pivot cache in the workbook declares a source type other than the supported worksheet source (e.g. an external data connection or OLAP cube), which the library cannot read or reconstruct.

Source

Thrown at errors.go:411

	return fmt.Errorf("must call the %s function before the SetRow function", name)
}

// newUnknownFilterTokenError defined the error message on receiving a unknown
// filter operator token.
func newUnknownFilterTokenError(token string) error {
	return fmt.Errorf("unknown operator: %s", token)
}

// newUnsupportedChartType defined the error message on receiving the chart
// type are unsupported.
func newUnsupportedChartType(chartType ChartType) error {
	return fmt.Errorf("unsupported chart type %d", chartType)
}

// newUnsupportedPivotCacheSourceType defined the error message on receiving the
// source type of pivot table cache.
func newUnsupportedPivotCacheSourceType(sourceType string) error {
	return fmt.Errorf("unsupported pivot table cache source type: %s", sourceType)
}

// newUnzipSizeLimitError defined the error message on unzip size exceeds the
// limit.
func newUnzipSizeLimitError(unzipSizeLimit int64) error {
	return fmt.Errorf("unzip size exceeds the %d bytes limit", unzipSizeLimit)
}

// newViewIdxError defined the error message on receiving a invalid sheet view
// index.
func newViewIdxError(viewIndex int) error {
	return fmt.Errorf("view index %d out of range", viewIndex)
}

View on GitHub (pinned to f2483381fb)

Solutions

1. Convert the pivot table's data source to a plain worksheet range inside the workbook (Data > Change Data Source) before processing it with excelize.
2. Guard GetPivotTable calls and skip pivot tables whose cache source is external, logging them instead of failing.
3. Remove or recreate external-connection pivot tables in Excel before handing the file to excelize.
4. If you need external-source pivots, keep them in a separate workbook not processed by the library.

Example fix

// before
pivots, err := f.GetPivotTable("Sheet1", "A3") // panics on external cache source
// after
if isWorksheetRangeSource(cacheXML) {
    pivots, err = f.GetPivotTable("Sheet1", "A3")
} else {
    log.Printf("skipping pivot with unsupported source type %s", sourceType)
}

// No public pre-check API for pivot cache source type; inspect the package XML
// before calling GetPivotTable in untrusted files:
// unzip xl/pivotCache/pivotCacheDefinition*.xml and confirm
// <cacheSource type="worksheet"> before processing.

pivots, err := f.GetPivotTable(sheet, cell)
if err != nil {
    if strings.Contains(err.Error(), "unsupported pivot table cache source type") {
        log.Printf("skipping pivot at %s!%s: external/unsupported cache source", sheet, cell)
        return nil // treat as non-fatal
    }
    return err
}

When it happens

Trigger: Calling f.GetPivotTable (or iterating pivot tables) on a workbook whose pivot cacheDefinition XML has a cacheSource type like 'external' or 'scenario' rather than 'worksheet', typically in files produced by Excel connected to external data.

Common situations: Opening corporate XLSX templates whose pivot tables pull from SQL Server/OLAP connections and calling GetPivotTable; copying pivot sheets between workbooks with external caches.

Related errors

• ErrParameterRequired
• ErrPivotTableShowValuesAsBaseField
• ErrPivotTableShowValuesAsBaseItem
• ErrPivotTableClassicLayout
• ErrUnsupportedPivotTableShowValuesAsType

AI-assisted analysis of qax-os/excelize@f2483381fb (2026-09-02). Data as JSON: /api/errors/c57560ed99b2a6f9. Report an issue: GitHub.