fill shading value must be between 0 and 16 for 'gradient' t

Error message

fill shading value must be between 0 and 16 for 'gradient' type

What it means

ErrFillGradientShading is returned by parseFormatStyleSet when Fill.Type is "gradient" and Fill.Shading is outside the inclusive range 0-16. The shading value controls the gradient direction/variant and must be a valid OOXML shading enum.

Source

Thrown at errors.go:71

	// 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.
	ErrFillPattern = errors.New("fill pattern value must be between 0 and 18")
	// ErrFontLength defined the error message on the length of the font
	// family name overflow.
	ErrFontLength = fmt.Errorf("the length of the font family name must be less than or equal to %d", MaxFontFamilyLength)
	// ErrFontSize defined the error message on the size of the font is invalid.
	ErrFontSize = fmt.Errorf("font size must be an integer from %d to %d points", MinFontSize, MaxFontSize)
	// ErrFormControlValue defined the error message for receiving a scroll
	// value exceeds limit.
	ErrFormControlValue = fmt.Errorf("scroll value must be an integer from 0 to %d", MaxFormControlValue)
	// ErrGroupSheets defined the error message on group sheets.
	ErrGroupSheets = errors.New("group worksheet must contain an active worksheet")
	// ErrImgExt defined the error message on receive an unsupported image
	// extension.

View on GitHub (pinned to f2483381fb)

Solutions

Set Fill.Shading to a value between 0 and 16 inclusive (e.g. 1 for horizontal).
Clamp the value: if Shading > 16 { Shading = 16 }; if Shading < 0 { Shading = 0 } before calling NewStyle.
Validate the range in your own code before constructing the Style.

Example fix

// before
f.NewStyle(&Style{Fill: Fill{Type: "gradient", Color: colors, Shading: 17}})
// after
shading := 17
if shading > 16 { shading = 16 }
f.NewStyle(&Style{Fill: Fill{Type: "gradient", Color: colors, Shading: shading}})

Defensive patterns

Strategy: validation

Validate before calling

if fill.Type == "gradient" && (fill.Shading < 0 || fill.Shading > 16) {
    return fmt.Errorf("shading %d out of range 0-16", fill.Shading)
}

Type guard

func validShading(s int) bool { return s >= 0 && s <= 16 }

Try / catch

_, err := f.NewStyle(&Style{Fill: fill})
if errors.Is(err, excelize.ErrFillGradientShading) {
    fill.Shading = 1 // safe default
    _, err = f.NewStyle(&Style{Fill: fill})
}

Prevention

Clamp user-supplied shading values to [0, 16] at input time.
Use named constants for the shading variants instead of raw ints.
Add a unit test covering boundary values 0, 16, and 17.

When it happens

Trigger: Calling f.NewStyle(&Style{Fill: Fill{Type: "gradient", Color: []string{"FFFFFF", "4E71BE"}, Shading: 17}}) or with a negative Shading value.

Common situations: Computing shading from user input without range checking, using arbitrary constants, or off-by-one errors when the valid maximum is 16.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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