qax-os/excelize · error

parameter 'PivotTableRange' parsing error: %s

Error message

parameter 'PivotTableRange' parsing error: %s

What it means

Excelize throws this when the PivotTableRange parameter passed to AddPivotTable cannot be parsed as a valid range reference. The range string is converted via NamespaceStrictName/CoordsToCellName-like parsing, and any malformed reference (bad sheet name quoting, reversed columns, or a multi-area/'non-rectangle' reference) fails. The underlying parse message is wrapped into the %s slot.

Source

Thrown at errors.go:375

	return fmt.Errorf("data fields %s appear both in the pivot table row fields and filter fields", strings.Join(data, ", "))
}

// newPivotTableDataRangeError defined the error message on receiving the
// invalid pivot table data range.
func newPivotTableDataRangeError(msg string) error {
	return fmt.Errorf("parameter 'DataRange' parsing error: %s", msg)
}

// newPivotTableSelectedItemError defined the error message on receiving the
// invalid pivot table selected item.
func newPivotTableSelectedItemError(item, field string) error {
	return fmt.Errorf("selected item %s does not exist in pivot table field %s", item, field)
}

// newPivotTableRangeError defined the error message on receiving the invalid
// pivot table range.
func newPivotTableRangeError(msg string) error {
	return fmt.Errorf("parameter 'PivotTableRange' parsing error: %s", msg)
}

// newPivotTableShowValuesAsBaseFieldError defined the error message on receiving
// the invalid pivot table "show values as" base field.
func newPivotTableShowValuesAsBaseFieldError(field string) error {
	return fmt.Errorf("base field %s does not exist in shared items", field)
}

// newStreamSetRowError defined the error message on the stream writer
// receiving the non-ascending row number.
func newStreamSetRowError(row int) error {
	return fmt.Errorf("row %d has already been written", row)
}

// newStreamSetRowOrderError defined the error message on calling the SetRow
// function before the order function.
func newStreamSetRowOrderError(name string) error {
	return fmt.Errorf("must call the %s function before the SetRow function", name)

View on GitHub (pinned to f2483381fb)

Solutions

1. Use the fully-qualified 'SheetName!TopLeft:BottomRight' form with top-left cell first, e.g. 'Sheet1!A1:E10'.
2. Validate the range by calling f.GetSheetName / excelize.CoordinatesToCellName on your corner cells before passing it in.
3. Quote sheet names that contain spaces or special characters as 'My Sheet'!A1:D10.
4. Confirm DataRange and PivotTableRange overlap the same worksheet and are rectangular ranges, not multiple ranges or named ranges.

Example fix

// before
f.AddPivotTable(&excelize.PivotTableOptions{
    DataRange:       "A1:E10",
    PivotTableRange: "Sheet1!D10:A1",
})
// after
f.AddPivotTable(&excelize.PivotTableOptions{
    DataRange:       "Sheet1!A1:E10",
    PivotTableRange: "Sheet1!G2:D10",
})

func validRange(rng string) bool {
    parts := strings.SplitN(rng, "!", 2)
    if len(parts) != 2 || parts[0] == "" {
        return false
    }
    corners := strings.Split(parts[1], ":")
    if len(corners) != 2 {
        return false
    }
    for _, c := range corners {
        if _, _, err := excelize.CellNameToCoordinates(c); err != nil {
            return false
        }
    }
    return true
}
// call before: if !validRange(opts.PivotTableRange) { return fmt.Errorf("bad PivotTableRange %q", opts.PivotTableRange) }

err := f.AddPivotTable(opts)
if err != nil {
    if strings.Contains(err.Error(), "parameter 'PivotTableRange' parsing error") {
        log.Printf("invalid pivot range %q: %v", opts.PivotTableRange, err)
        return
    }
    return err
}

When it happens

Trigger: Calling f.AddPivotTable(&PivotTableOptions{...}) or parseFormatPivotTableSet with DataRange, PivotTableRange, or FilterRange strings that fail range parsing, e.g. 'Sheet1:A1:D10' (missing !), 'Sheet1!D1:A10' non-topleft ordering, or a whole-column/open range.

Common situations: Hand-building PivotTableOptions with copy-pasted range strings; swapping the range corners; forgetting the sheet-qualified form 'Sheet1!A1:D10'; programmatic range built from wrong row/col variables (zero or negative coordinates).

Related errors

• ErrParameterRequired
• ErrPivotTableShowValuesAsBaseField
• ErrPivotTableShowValuesAsBaseItem
• ErrPivotTableClassicLayout
• ErrUnsupportedPivotTableShowValuesAsType

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