What causes "password length invalid" in qax-os/excelize?

Supply a non-empty password within MaxFieldLength UTF-16 units

ErrPasswordLengthInvalid

ErrPasswordLengthInvalid

Error message

password length invalid

What it means

ErrPasswordLengthInvalid is returned when a password is empty or exceeds MaxFieldLength UTF-16 code units. It is raised in standardKeyEncryption (file encryption) and genISOPasswdHash (sheet/workbook protection hash generation).

Source

Thrown at errors.go:129

	ErrMaxGraphicNameLength = fmt.Errorf("the name length exceeds the %d characters limit", MaxGraphicNameLength)
	// ErrOptionsUnzipSizeLimit defined the error message for receiving
	// invalid UnzipSizeLimit and UnzipXMLSizeLimit.
	ErrOptionsUnzipSizeLimit = errors.New("the value of UnzipSizeLimit should be greater than or equal to UnzipXMLSizeLimit")
	// ErrOutlineLevel defined the error message on receive an invalid outline
	// level number.
	ErrOutlineLevel = errors.New("invalid outline level")
	// ErrPageSetupAdjustTo defined the error message for receiving a page setup
	// adjust to value exceeds limit.
	ErrPageSetupAdjustTo = errors.New("adjust to value must be an integer from 0 to 400")
	// ErrParameterInvalid defined the error message on receive the invalid
	// parameter.
	ErrParameterInvalid = errors.New("parameter is invalid")
	// ErrParameterRequired defined the error message on receive the empty
	// parameter.
	ErrParameterRequired = errors.New("parameter is required")
	// ErrPasswordLengthInvalid defined the error message on invalid password
	// length.
	ErrPasswordLengthInvalid = errors.New("password length invalid")
	// ErrPivotTableShowValuesAsBaseField defined the error message on enable
	// this kind of "show values as" type requires a base field.
	ErrPivotTableShowValuesAsBaseField = errors.New("this kind of show values as type requires a base field")
	// ErrPivotTableShowValuesAsBaseItem defined the error message on enable
	// this kind of "show values as" type and base field requires a base item.
	ErrPivotTableShowValuesAsBaseItem = errors.New("this kind of show values as type and base field requires a base item")
	// ErrPivotTableClassicLayout defined the error message on enable
	// ClassicLayout and CompactData in the same time.
	ErrPivotTableClassicLayout = errors.New("cannot enable ClassicLayout and CompactData in the same time")
	// ErrSave defined the error message for saving file.
	ErrSave = errors.New("no path defined for file, consider File.WriteTo or File.Write")
	// ErrSheetIdx defined the error message on receive the invalid worksheet
	// index.
	ErrSheetIdx = errors.New("invalid worksheet index")
	// ErrSheetNameBlank defined the error message on receive the blank sheet
	// name.
	ErrSheetNameBlank = errors.New("the sheet name can not be blank")
	// ErrSheetNameInvalid defined the error message on receive the sheet name

View on GitHub (pinned to f2483381fb)

Solutions

Supply a non-empty password within MaxFieldLength UTF-16 units
Check the password length in your code before calling Encrypt/ProtectSheet/ProtectWorkbook
Trim or hash long secrets to a bounded value before use

Example fix

// before
password := os.Getenv("XLSX_PASS") // may be empty
err := f.ProtectSheet("Sheet1", &excelize.SheetProtectionOptions{Password: password})
// after
password := os.Getenv("XLSX_PASS")
if len(password) == 0 || len(utf16.Encode([]rune(password))) > 255 {
    return errors.New("password length invalid")
}
err := f.ProtectSheet("Sheet1", &excelize.SheetProtectionOptions{Password: password})

Defensive patterns

Strategy: validation

Validate before calling

func validPassword(p string) bool {
    n := len(utf16.Encode([]rune(p)))
    return n >= 1 && n <= 255 // within MaxFieldLength
}

Type guard

func validPassword(p string) bool { return len(utf16.Encode([]rune(p))) >= 1 && len(utf16.Encode([]rune(p))) <= 255 }

Try / catch

if err := f.ProtectSheet(sheet, opts); errors.Is(err, excelize.ErrPasswordLengthInvalid) { // prompt for a new password }

Prevention

Check password length in UTF-16 units before encrypting or protecting
Never use empty strings from unset env vars as passwords
Hash or truncate overly long secrets to a bounded length

When it happens

Trigger: Calling File.Encrypt/SaveAs with encryption where the password is empty or too long; File.ProtectSheet or ProtectWorkbook with a password of length 0 or greater than MaxFieldLength (measured with countUTF16String).

Common situations: Empty password variables from un-set env vars or config keys; very long generated tokens used as passwords; multi-byte characters pushing the UTF-16 length over the limit.

Related errors

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