What causes "parameter is required" in qax-os/excelize?

Check for nil before calling and construct a valid options struct

ErrParameterRequired

ErrParameterRequired

Error message

parameter is required

What it means

ErrParameterRequired is returned when a required option struct or string is empty/nil. parseFormatPivotTableSet returns it if a nil *PivotTableOptions is passed, and adjustRange returns it if the range string is empty.

Source

Thrown at errors.go:126

	ErrMaxGraphicAltTextLength = fmt.Errorf("the alt text length exceeds the %d characters limit", MaxGraphicAltTextLength)
	// ErrMaxGraphicNameLength defined the error message on receiving the
	// graphic name length exceeds the limit.
	ErrMaxGraphicNameLength = fmt.Errorf("the name length exceeds the %d characters limit", MaxGraphicNameLength)
	// ErrOptionsUnzipSizeLimit defined the error message for receiving
	// invalid UnzipSizeLimit and UnzipXMLSizeLimit.
	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

View on GitHub (pinned to f2483381fb)

Solutions

Check for nil before calling and construct a valid options struct
Ensure the range field is a non-empty string like "Sheet1!A1:E31"
Guard your code: return your own validation error before invoking the library

Example fix

// before
var opts *PivotTableOptions
f.AddPivotTable(opts) // ErrParameterRequired
// after
opts := &excelize.PivotTableOptions{DataRange: "Sheet1!A1:E31", PivotTableRange: "Sheet1!G2:M34"}
if err := f.AddPivotTable(opts); err != nil { return err }

Defensive patterns

Strategy: validation

Validate before calling

if opts == nil || strings.TrimSpace(opts.PivotTableRange) == "" {
    return errors.New("pivot table options and range are required")
}
err := f.AddPivotTable(opts)

Type guard

func optsProvided[T any](o *T) bool { return o != nil }

Try / catch

if err := f.AddPivotTable(opts); errors.Is(err, excelize.ErrParameterRequired) { // build defaults and retry }

Prevention

Never pass nil options structs to excelize APIs
Ensure range strings are non-empty and fully qualified (Sheet!Range)
Construct options with explicit field values instead of zero-value structs

When it happens

Trigger: f.AddPivotTable(nil) or f.AddPivotTable(&PivotTableOptions{...}) where PivotTableRange is ""; passing an empty sparkline format or an empty range string into any API that adjusts ranges.

Common situations: Options structs built conditionally and left nil; range strings assembled from config values that default to empty string; zero-value structs used accidentally.

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/386ff4f87f78d2af. Report an issue: GitHub.