ErrPivotTableShowValuesAsBaseItem

ErrPivotTableShowValuesAsBaseItem

Error message

this kind of show values as type and base field requires a base item

What it means

ErrPivotTableShowValuesAsBaseItem is returned when a pivot table data field's "show values as" configuration specifies a BaseField but the required BaseItem is empty. The base item names the specific item of the base field to compare against.

Source

Thrown at errors.go:135

	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
	// name length exceeds the limit.
	ErrSheetNameLength = fmt.Errorf("the sheet name length exceeds the %d characters limit", MaxSheetNameLength)
	// ErrSheetNameSingleQuote defined the error message on the first or last

View on GitHub (pinned to f2483381fb)

Solutions

Set ShowValuesAs.BaseItem to an item that exists under the base field, e.g. "2023"
Verify the item name exactly matches a shared item of the base field
Only enable ShowValuesAs types requiring a base item when both values are known

Example fix

// before
ShowValuesAs: excelize.PivotTableShowValuesAs{Type: "percentDifferenceOf", BaseField: "Year"}
// after
ShowValuesAs: excelize.PivotTableShowValuesAs{Type: "percentDifferenceOf", BaseField: "Year", BaseItem: "2023"}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Always set BaseItem together with BaseField for ShowValuesAs types that need it
Verify BaseItem matches an existing item of the base field
Reject empty config-sourced item names early

When it happens

Trigger: f.AddPivotTable with opts.Data[i].ShowValuesAs having BaseField set but BaseItem == ""; setPivotTableShowValuesAsBaseItem (pivotTable.go:947) returns it when baseItem is empty, before validating the item against shared items.

Common situations: Setting BaseField but forgetting BaseItem when building options; BaseItem sourced from config/user input that is empty; misunderstanding that both base field AND base item are needed for certain ShowValuesAs types.

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/75a9c32a09356126. Report an issue: GitHub.