What causes "workbook protect password not match" in qax-os/excelize?

Supply the exact password used with ProtectWorkbook

ErrUnprotectWorkbookPassword

ErrUnprotectWorkbookPassword

Error message

workbook protect password not match

What it means

ErrUnprotectWorkbookPassword indicates that the password supplied to UnprotectWorkbook failed hash verification against the workbook protection hash. The library throws it from UnprotectWorkbook when wb.WorkbookProtection.WorkbookHashValue does not match the computed hash.

Source

Thrown at errors.go:191

	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")
	// ErrUnsupportedHashAlgorithm defined the error message on unsupported
	// hash algorithm.
	ErrUnsupportedHashAlgorithm = errors.New("unsupported hash algorithm")
	// ErrUnsupportedNumberFormat defined the error message on unsupported
	// number format expression.
	ErrUnsupportedNumberFormat = errors.New("unsupported number format token")
	// ErrUnsupportedPivotTableShowValuesAsType defined the error message on
	// receiving the unsupported pivot table "show values as" type.
	ErrUnsupportedPivotTableShowValuesAsType = errors.New("unsupported pivot table show values as type")
	// ErrWorkbookFileFormat defined the error message on receive an
	// unsupported workbook file format.
	ErrWorkbookFileFormat = errors.New("unsupported workbook file format")
	// ErrWorkbookPassword defined the error message on receiving the incorrect
	// workbook password.
	ErrWorkbookPassword = errors.New("the supplied open workbook password is not correct")

View on GitHub (pinned to f2483381fb)

Solutions

Supply the exact password used with ProtectWorkbook
If lost, remove workbookProtection element from workbook.xml manually
Re-create the workbook without protection

Example fix

// before
err := f.UnprotectWorkbook("wrongPassword")
// after
err := f.UnprotectWorkbook("password") // actual protection password

Defensive patterns

Strategy: try-catch

Try / catch

if err := f.UnprotectWorkbook(pw); err != nil {
	if errors.Is(err, excelize.ErrUnprotectWorkbookPassword) {
		return fmt.Errorf("incorrect workbook password")
	}
	return err
}

Prevention

Store the workbook protection password used in ProtectWorkbook
Use the same algorithm and password across save/load cycles
Never assume a default password

When it happens

Trigger: Calling f.UnprotectWorkbook("wrongPassword") on a password-protected workbook (workbook.go:179 hash comparison fails).

Common situations: Wrong or mistyped password; protection password set by another application or user; hash algorithm mismatch after file round-trip.

Related errors

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