fill color value must be an array of two colors for 'gradien

Error message

fill color value must be an array of two colors for 'gradient' type

What it means

ErrFillGradientColor is returned by parseFormatStyleSet when Fill.Type is "gradient" but Fill.Color does not contain exactly two color strings. Gradient fills in this library are two-stop gradients, so the Color slice must be a two-element array.

Source

Thrown at errors.go:68

	// 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.
	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.

View on GitHub (pinned to f2483381fb)

Solutions

Provide exactly two color strings in Fill.Color, e.g. []string{"FFFFFF", "4E71BE"}.
If you only have one color, switch Fill.Type to "pattern" instead of "gradient".
Validate len(style.Fill.Color) == 2 before calling NewStyle.

Example fix

// before
f.NewStyle(&Style{Fill: Fill{Type: "gradient", Color: []string{"FFFFFF"}, Shading: 0}})
// after
f.NewStyle(&Style{Fill: Fill{Type: "gradient", Color: []string{"FFFFFF", "4E71BE"}, Shading: 0}})

Defensive patterns

Strategy: validation

Validate before calling

if fill.Type == "gradient" && len(fill.Color) != 2 {
    return errors.New("gradient fill requires exactly two colors")
}

Type guard

func isTwoColorSlice(c []string) bool { return len(c) == 2 }

Try / catch

_, err := f.NewStyle(&Style{Fill: fill})
if errors.Is(err, excelize.ErrFillGradientColor) {
    fill.Color = append(fill.Color, "FFFFFF") // or fix input
}

Prevention

Always construct gradient colors as a literal two-element slice.
Centralize fill construction in a helper that enforces the color count.
Switch to pattern fill when only one color is needed.

When it happens

Trigger: Calling f.NewStyle(&Style{Fill: Fill{Type: "gradient", Color: []string{"FFFFFF"}, Shading: 0}}) with one color, three colors, or no colors at all.

Common situations: Assuming gradient works like pattern fill (which takes 0 or 1 color), building the color list programmatically and ending up with a single entry, or forgetting to set Color entirely.

Related errors

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