qax-os/excelize · error

ErrTransparency

ErrTransparency

Error message

transparency value must be an integer from 0 to 100

What it means

ErrTransparency is returned when a chart or shape fill Transparency value is outside 0-100. parseChartOptions/parseSeries (chart.go:593, 617) and parseShapeOptions validate it because Excel stores transparency as a percentage and out-of-range values produce invalid XML.

Source

Thrown at errors.go:176

	ErrSparkline = errors.New("must have the same number of 'Location' and 'Range' parameters")
	// ErrSparklineLocation defined the error message on missing Location
	// parameters
	ErrSparklineLocation = errors.New("parameter 'Location' is required")
	// ErrSparklineRange defined the error message on missing sparkline Range
	// parameters
	ErrSparklineRange = errors.New("parameter 'Range' is required")
	// ErrSparklineStyle defined the error message on receive the invalid
	// sparkline Style parameters.
	ErrSparklineStyle = errors.New("parameter 'Style' value must be an integer from 0 to 35")
	// ErrSparklineType defined the error message on receive the invalid
	// sparkline Type parameters.
	ErrSparklineType = errors.New("parameter 'Type' value must be one of 'line', 'column' or 'win_loss'")
	// ErrTotalSheetHyperlinks defined the error message on hyperlinks count
	// overflow.
	ErrTotalSheetHyperlinks = errors.New("over maximum limit hyperlinks in a worksheet")
	// ErrTransparency defined the error message for receiving a transparency
	// value exceeds limit.
	ErrTransparency = errors.New("transparency value must be an integer from 0 to 100")
	// ErrUnknownEncryptMechanism defined the error message on unsupported
	// encryption mechanism.
	ErrUnknownEncryptMechanism = errors.New("unknown encryption mechanism")
	// ErrUnprotectSheet defined the error message on worksheet has set no
	// protection.
	ErrUnprotectSheet = errors.New("worksheet has set no protect")
	// ErrUnprotectSheetPassword defined the error message on remove sheet
	// protection with password verification failed.
	ErrUnprotectSheetPassword = errors.New("worksheet protect password not match")
	// ErrUnprotectWorkbook defined the error message on workbook has set no
	// protection.
	ErrUnprotectWorkbook = errors.New("workbook has set no protect")
	// ErrUnprotectWorkbookPassword defined the error message on remove workbook
	// protection with password verification failed.
	ErrUnprotectWorkbookPassword = errors.New("workbook protect password not match")
	// ErrUnsupportedEncryptMechanism defined the error message on unsupported
	// encryption mechanism.
	ErrUnsupportedEncryptMechanism = errors.New("unsupported encryption mechanism")

View on GitHub (pinned to f2483381fb)

Solutions

1. Clamp Transparency into [0,100] before AddChart/AddShape
2. Convert opacity to transparency: transparency = 100 - opacity
3. Convert fractional alpha: transparency = int(alpha * 100)

Example fix

// before
chartOpts.Fill.Transparency = 128 // alpha-style value
f.AddChart("Sheet1", "A1", chartOpts)
// after
t := 100 - opacityPercent
if t < 0 { t = 0 } else if t > 100 { t = 100 }
chartOpts.Fill.Transparency = t
f.AddChart("Sheet1", "A1", chartOpts)

if t < 0 || t > 100 {
    t = 0
}
opts.Fill.Transparency = t

func transparencyValid(t int) bool {
    return t >= 0 && t <= 100
}

if _, err := f.AddChart("Sheet1", "A1", opts); err != nil {
    if errors.Is(err, excelize.ErrTransparency) {
        // clamp fill and all series transparency values, then retry
    }
    return err
}

When it happens

Trigger: Calling f.AddChart or f.AddShape with opts.Fill.Transparency < 0 or > 100, or any series whose series.Fill.Transparency is out of range (chart.go:617).

Common situations: Confusing opacity (0-100, opaque first) with transparency (0-100, transparent last) and passing 100-opacity as transparency; computing alpha (0-255 or 0.0-1.0) and forgetting to convert to percent.

Related errors

• ErrSparklineStyle
• fill type value must be one of 'gradient' or 'pattern'
• fill color value must be an array of two colors for 'gradien
• fill shading value must be between 0 and 16 for 'gradient' t
• fill color value must be empty or an array of one color for

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