qax-os/excelize · warning

no defined name on the scope

Error message

no defined name on the scope

What it means

ErrDefinedNameScope is returned when a defined name cannot be found on the given scope, most notably from DeleteDefinedName (sheet.go:1861). Excelize looks up the defined name by Name (and Scope); if no match exists it returns this error instead of failing silently.

Source

Thrown at errors.go:58

	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.
	ErrFillPatternColor = errors.New("fill color value must be empty or an array of one color for 'pattern' type")
	// ErrFillPattern defined the error message on receive an invalid fill
	// pattern.

View on GitHub (pinned to f2483381fb)

Solutions

1. Only call DeleteDefinedName for names you know exist, or check the error and ignore this sentinel when deletion is best-effort.
2. Pass the same Scope value (0 for workbook scope, sheet index otherwise) used when the name was created.
3. Verify the exact name string matches, including case and spaces.

Example fix

// before
err := f.DeleteDefinedName(&DefinedName{Name: "No Exist Defined Name"})
// after
err := f.DeleteDefinedName(&DefinedName{Name: "MyName", Scope: 0})
if err != nil && err != excelize.ErrDefinedNameScope {
    return err
}

// Keep a set of defined names you created:
if !createdNames[name] { skip deletion }

func definedNameExists(f *excelize.File, name string) bool {
	return f.DeleteDefinedName(&excelize.DefinedName{Name: name}) != excelize.ErrDefinedNameScope
}

err := f.DeleteDefinedName(&excelize.DefinedName{Name: name})
if errors.Is(err, excelize.ErrDefinedNameScope) {
	return nil // nothing to delete; not an error for best-effort cleanup
}

When it happens

Trigger: Calling f.DeleteDefinedName(&DefinedName{Name: "No Exist Defined Name"}) for a name that was never created or was created on a different scope/sheet than the one specified.

Common situations: Cleanup code deleting names that may not exist yet; scope mismatch (name defined workbook-wide but deleted with a sheet scope, or vice versa); typos in the name string.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• the same name already exists on the scope
• data validation range exceeds limit
• the same name sheet already exists
• the same name table already exists
• 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/2277761c8973f2e9. Report an issue: GitHub.