qax-os/excelize · error

parameter 'DataRange' parsing error: %s

Error message

parameter 'DataRange' parsing error: %s

What it means

Returned by newPivotTableDataRangeError when the Options.DataRange of a pivot table cannot be parsed into a valid range reference, wrapping the underlying parse message. The pivot cache and layout computation depend on a well-formed rectangular range, so parsing is validated up front in parseFormatPivotTableSet, addPivotCache, getTableFieldsOrder, and getPivotTableDataRange.

Source

Thrown at errors.go:363

	return fmt.Errorf("sheet %s is not a worksheet", name)
}

// newPivotTableColFieldsError defined the error message on same data field
// appears both in the pivot table column fields and filter fields.
func newPivotTableColFieldsError(data []string) error {
	return fmt.Errorf("data fields %s appear both in the pivot table column fields and filter fields", strings.Join(data, ", "))
}

// newPivotTableRowFieldsError defined the error message on same data field
// appears both in the pivot table row fields and filter fields.
func newPivotTableRowFieldsError(data []string) error {
	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)

View on GitHub (pinned to f2483381fb)

Solutions

1. Fix the DataRange string to a valid contiguous range, e.g. "Sheet1!A1:E10" (quote sheet names with spaces: "'My Sheet'!A1:E10")
2. Use f.CellsCoordinates or CoordinatesToRangeName-style helpers to build the reference instead of hand-concatenating
3. Ensure the range spans at least a header row plus one data row and exists on a worksheet
4. Read the wrapped %s message for the exact parsing failure

Example fix

// before
opts := &excelize.Options{DataRange: "A1:B"} // invalid
// after
opts := &excelize.Options{DataRange: "Sheet1!A1:E10"}

func validateDataRange(f *excelize.File, ref string) error {
    parts := strings.SplitN(ref, "!", 2)
    if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
        return fmt.Errorf("DataRange must be like Sheet1!A1:E10, got %q", ref)
    }
    coords, err := f.CellsCoordinates(parts[1])
    if err != nil {
        return err
    }
    _ = coords
    return nil
}

null

if err := f.AddPivotTable(opts.DataRange, opts.PivotTableRange, opts); err != nil {
    if strings.Contains(err.Error(), "'DataRange' parsing error") {
        return fmt.Errorf("check DataRange %q: %w", opts.DataRange, err)
    }
    return err
}

When it happens

Trigger: Passing Options{DataRange: ...} with a malformed reference (empty string, wrong sheet qualifier, reversed rows/cols, single-cell or non-contiguous range, invalid format like 'Sheet1!A1:B' or 'NotARange') to AddPivotTable or related pivot helpers.

Common situations: Building the range string with fmt.Sprintf and getting coordinates wrong; using coordinates from another sheet without the sheet-name prefix (or with an unquoted sheet name containing spaces); data range deleted/moved after the pivot options were captured.

Related errors

• ErrParameterRequired
• ErrPivotTableShowValuesAsBaseField
• ErrPivotTableShowValuesAsBaseItem
• ErrPivotTableClassicLayout
• ErrUnsupportedPivotTableShowValuesAsType

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