qax-os/excelize · error

ErrTotalSheetHyperlinks

ErrTotalSheetHyperlinks

Error message

over maximum limit hyperlinks in a worksheet

What it means

ErrTotalSheetHyperlinks is returned by SetCellHyperLink when the worksheet already contains the maximum number of hyperlinks (TotalSheetHyperlinks = 65530; Excel's limit). cell.go:1168 checks the count before adding another.

Source

Thrown at errors.go:173

	ErrSheetNameSingleQuote = errors.New("the first or last character of the sheet name can not be a single quote")
	// ErrSparkline defined the error message on receive the invalid sparkline
	// parameters.
	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")

View on GitHub (pinned to f2483381fb)

Solutions

1. Count ws.Hyperlinks.Hyperlink before adding and stop below 65530
2. Consolidate links (one link per cell block or a summary sheet) instead of one per cell
3. Store the URLs as cell text or in a separate data sheet rather than as hyperlinks

Example fix

// before
for _, row := range rows {
    f.SetCellHyperLink("Sheet1", row.Cell, row.URL, "External")
}
// after
for i, row := range rows {
    if i >= 65530 {
        break // Excel hyperlink limit
    }
    f.SetCellHyperLink("Sheet1", row.Cell, row.URL, "External")
}

const maxLinks = 65530
if linkCount["Sheet1"] >= maxLinks {
    return errors.New("worksheet hyperlink limit reached")
}

if err := f.SetCellHyperLink("Sheet1", cell, url, "External"); err != nil {
    if errors.Is(err, excelize.ErrTotalSheetHyperlinks) {
        // render remaining URLs as plain text instead
    }
    return err
}

When it happens

Trigger: Calling f.SetCellHyperLink on a worksheet whose ws.Hyperlinks.Hyperlink slice already exceeds 65530 entries, e.g. in tests that pre-populate 65530 hyperlinks then add A65531.

Common situations: Bulk-linking every cell in a large generated report; importing data with a link per row far beyond Excel's 65,530 hyperlink limit; looping SetCellHyperLink without counting existing links.

Related errors

• 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
• fill pattern value must be between 0 and 18

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