ErrPivotTableShowValuesAsBaseField

ErrPivotTableShowValuesAsBaseField

Error message

this kind of show values as type requires a base field

What it means

ErrPivotTableShowValuesAsBaseField is returned when a pivot table data field uses a "show values as" calculation that requires a BaseField, but BaseField is an empty string. The base field identifies the field against which values are shown.

Source

Thrown at errors.go:132

	ErrOptionsUnzipSizeLimit = errors.New("the value of UnzipSizeLimit should be greater than or equal to UnzipXMLSizeLimit")
	// ErrOutlineLevel defined the error message on receive an invalid outline
	// level number.
	ErrOutlineLevel = errors.New("invalid outline level")
	// ErrPageSetupAdjustTo defined the error message for receiving a page setup
	// adjust to value exceeds limit.
	ErrPageSetupAdjustTo = errors.New("adjust to value must be an integer from 0 to 400")
	// ErrParameterInvalid defined the error message on receive the invalid
	// parameter.
	ErrParameterInvalid = errors.New("parameter is invalid")
	// ErrParameterRequired defined the error message on receive the empty
	// parameter.
	ErrParameterRequired = errors.New("parameter is required")
	// ErrPasswordLengthInvalid defined the error message on invalid password
	// length.
	ErrPasswordLengthInvalid = errors.New("password length invalid")
	// ErrPivotTableShowValuesAsBaseField defined the error message on enable
	// this kind of "show values as" type requires a base field.
	ErrPivotTableShowValuesAsBaseField = errors.New("this kind of show values as type requires a base field")
	// ErrPivotTableShowValuesAsBaseItem defined the error message on enable
	// this kind of "show values as" type and base field requires a base item.
	ErrPivotTableShowValuesAsBaseItem = errors.New("this kind of show values as type and base field requires a base item")
	// ErrPivotTableClassicLayout defined the error message on enable
	// ClassicLayout and CompactData in the same time.
	ErrPivotTableClassicLayout = errors.New("cannot enable ClassicLayout and CompactData in the same time")
	// ErrSave defined the error message for saving file.
	ErrSave = errors.New("no path defined for file, consider File.WriteTo or File.Write")
	// ErrSheetIdx defined the error message on receive the invalid worksheet
	// index.
	ErrSheetIdx = errors.New("invalid worksheet index")
	// ErrSheetNameBlank defined the error message on receive the blank sheet
	// name.
	ErrSheetNameBlank = errors.New("the sheet name can not be blank")
	// ErrSheetNameInvalid defined the error message on receive the sheet name
	// contains invalid characters.
	ErrSheetNameInvalid = errors.New("the sheet can not contain any of the characters :\\/?*[or]")
	// ErrSheetNameLength defined the error message on receiving the sheet

View on GitHub (pinned to f2483381fb)

Solutions

Set ShowValuesAs.BaseField to a field name present in DataRange, e.g. "Year"
Choose a ShowValuesAs type that does not require a base field, or drop ShowValuesAs
Validate Data[i].ShowValuesAs before calling AddPivotTable

Example fix

// before
Data: []excelize.PivotTableDataField{{Data: "Sales", ShowValuesAs: excelize.PivotTableShowValuesAs{Type: "percentDifferenceOf"}}}
// after
Data: []excelize.PivotTableDataField{{Data: "Sales", ShowValuesAs: excelize.PivotTableShowValuesAs{Type: "percentDifferenceOf", BaseField: "Year", BaseItem: "2023"}}}

Defensive patterns

Strategy: validation

Validate before calling

for _, d := range opts.Data {
    if d.ShowValuesAs.Type != "" && d.ShowValuesAs.BaseField == "" {
        return errors.New("ShowValuesAs requires BaseField")
    }
}
err := f.AddPivotTable(opts)

Type guard

func needsBaseField(sv excelize.PivotTableShowValuesAs) bool { return sv.Type != "" && sv.BaseField == "" }

Try / catch

if err := f.AddPivotTable(opts); errors.Is(err, excelize.ErrPivotTableShowValuesAsBaseField) { // set BaseField and retry }

Prevention

Set BaseField whenever ShowValuesAs.Type is used
Ensure BaseField names a field within DataRange
Validate Data fields before AddPivotTable

When it happens

Trigger: Adding a pivot table via f.AddPivotTable where opts.Data[i].ShowValuesAs has a type that requires a base field (e.g. percent difference of) while ShowValuesAs.BaseField == "".

Common situations: Constructing PivotTableOptions programmatically and forgetting the BaseField; copying options and dropping the nested ShowValuesAs settings; using ShowValuesAs types without realizing some require base field/item.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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