qax-os/excelize · error

the same name already exists on the scope

Error message

the same name already exists on the scope

What it means

ErrDefinedNameDuplicate is returned by SetDefinedName when a defined name with the same Name already exists on the same scope (workbook-wide or a specific sheet). Excel requires defined names to be unique within their scope, so Excelize rejects the duplicate at sheet.go:1819 rather than overwriting silently.

Source

Thrown at errors.go:55

	ErrColumnNumber = fmt.Errorf("the column number must be greater than or equal to %d and less than or equal to %d", MinColumns, MaxColumns)
	// ErrColumnWidth defined the error message on receive an invalid column
	// width.
	ErrColumnWidth = fmt.Errorf("the width of the column must be less than or equal to %d characters", MaxColumnWidth)
	// ErrCoordinates defined the error message on invalid coordinates tuples
	// length.
	ErrCoordinates = errors.New("coordinates length must be 4")
	// ErrCustomNumFmt defined the error message on receive the empty custom
	// number format.
	ErrCustomNumFmt = errors.New("custom number format can not be empty")
	// ErrDataValidationFormulaLength defined the error message for receiving a
	// data validation formula length that exceeds the limit.
	ErrDataValidationFormulaLength = fmt.Errorf("data validation must be 0-%d characters", MaxFieldLength)
	// ErrDataValidationRange defined the error message on set decimal range
	// exceeds limit.
	ErrDataValidationRange = errors.New("data validation range exceeds limit")
	// ErrDefinedNameDuplicate defined the error message on the same name
	// already exists on the scope.
	ErrDefinedNameDuplicate = errors.New("the same name already exists on the scope")
	// ErrDefinedNameScope defined the error message on not found defined name
	// in the given scope.
	ErrDefinedNameScope = errors.New("no defined name on the scope")
	// ErrExistsSheet defined the error message on given sheet already exists.
	ErrExistsSheet = errors.New("the same name sheet already exists")
	// ErrExistsTableName defined the error message on given table already
	// exists.
	ErrExistsTableName = errors.New("the same name table already exists")
	// ErrFillType defined the error message on receive an invalid fill type.
	ErrFillType = errors.New("fill type value must be one of 'gradient' or 'pattern'")
	// ErrFillGradientColor defined the error message on receive an invalid fill
	// color for 'gradient' type.
	ErrFillGradientColor = errors.New("fill color value must be an array of two colors for 'gradient' type")
	// ErrFillGradientShading defined the error message on receive an invalid
	// fill shading for 'gradient' type.
	ErrFillGradientShading = errors.New("fill shading value must be between 0 and 16 for 'gradient' type")
	// ErrFillPatternColor defined the error message on receive an invalid fill
	// color for 'pattern' type.

View on GitHub (pinned to f2483381fb)

Solutions

1. Call f.DeleteDefinedName(&DefinedName{Name: X, Scope: s}) before re-setting the name.
2. Track already-created defined names in your generation code so SetDefinedName runs only once.
3. If the goal is to update, delete-then-set in one helper function.

Example fix

// before
f.SetDefinedName(&DefinedName{Name: "name1", RefersTo: "Sheet1!$A$2:$D$5"})
f.SetDefinedName(&DefinedName{Name: "name1", RefersTo: "Sheet1!$B$2:$D$5"}) // ErrDefinedNameDuplicate
// after
f.DeleteDefinedName(&DefinedName{Name: "name1"})
f.SetDefinedName(&DefinedName{Name: "name1", RefersTo: "Sheet1!$B$2:$D$5"})

// Excelize exposes no public name-lookup helper; track names yourself:
created := map[string]bool{}
key := fmt.Sprintf("%s:%d", name, scope)
if created[key] { f.DeleteDefinedName(&excelize.DefinedName{Name: name, Scope: scope}) }
f.SetDefinedName(&excelize.DefinedName{Name: name, RefersTo: ref, Scope: scope})
created[key] = true

func hasDefinedName(f *excelize.File, name string, scope int) bool {
	err := f.DeleteDefinedName(&excelize.DefinedName{Name: name, Scope: scope})
	return err != excelize.ErrDefinedNameScope
}

err := f.SetDefinedName(dn)
if errors.Is(err, excelize.ErrDefinedNameDuplicate) {
	_ = f.DeleteDefinedName(&excelize.DefinedName{Name: dn.Name, Scope: dn.Scope})
	err = f.SetDefinedName(dn)
}

When it happens

Trigger: Calling f.SetDefinedName(&DefinedName{Name: X, RefersTo: ..., Scope: s}) twice with the same X and same scope; e.g. re-running setup code that defines "name1" -> "Sheet1!$A$2:$D$5" without first deleting the existing definition.

Common situations: Idempotent workbook-generation scripts run twice against the same file; copying template macros that already contain defined names; updating a name's RefersTo without deleting the old one first.

Related errors

• no defined name on the scope
• the same name sheet already exists
• the same name table already exists
• data validation range exceeds limit
• fill type value must be one of 'gradient' or 'pattern'

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