gofiber/fiber · error

encryption key must be 16, 24, or 32 bytes

Error message

encryption key must be 16, 24, or 32 bytes

What it means

Returned by middleware/encryptcookie.decodeKey when a base64-decoded key is not 16, 24, or 32 bytes (AES-128/192/256 key sizes). It is also panicked from the config default path (utils.go:100) when the package-level key fails validation. The lengths map directly to AES; anything else cannot create a cipher.

Solutions

1. Generate a proper key: `openssl rand -base64 32` (32 bytes) and use that as Key.
2. Confirm the decoded length is exactly 16, 24, or 32 bytes; the error fires after base64 decode, not on the raw string length.
3. Keep the key consistent across all instances sharing encrypted cookies (same size and value).
4. If migrating key sizes, decrypt existing cookies with the old key and re-encrypt with the new one.

Example fix

// before
Key: "my-secret-password" // not a valid AES key
// after
// generated once: openssl rand -base64 32
Key: "cGFzc3dvcmRwYXNzd29yZHBhc3N3b3JkcGFzc3dvcmQ=" // base64 of 32 bytes

func validEncryptKey(b64 string) error {
    b, err := base64.StdEncoding.DecodeString(b64)
    if err != nil { return err }
    switch len(b) {
    case 16, 24, 32: return nil
    default: return encryptcookie.ErrInvalidKeyLength
    }
}

if err := encryptcookie.ValidateKey(key); err != nil {
    if errors.Is(err, encryptcookie.ErrInvalidKeyLength) {
        // regenerate key with correct length before continuing
    }
    return err
}

When it happens

Trigger: Setting encryptcookie.Config.Key to a base64 string whose decoded length is not 16/24/32 bytes; using a raw passphrase instead of a key; a key generated for a different AES size; truncation or padding in the base64.

Common situations: Pasting a hex or ASCII password into Key instead of a base64-encoded random key; env var truncated; generating a key with the wrong byte length; rotating from a 16-byte to a 32-byte key but not updating the env on all instances.

Related errors

• failed to base64-decode key
• decode SHA256 password: invalid length
• failed to create AES cipher
• failed to create GCM mode
• failed to decrypt ciphertext

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/d43dbc9255f8b9fc. Report an issue: GitHub.

Appendix: source

Thrown at middleware/encryptcookie/utils.go:14

package encryptcookie

import (
	"crypto/aes"
	"crypto/cipher"
	"crypto/rand"
	"encoding/base64"
	"errors"
	"fmt"
	"slices"
)

var (
	ErrInvalidKeyLength      = errors.New("encryption key must be 16, 24, or 32 bytes")
	ErrInvalidEncryptedValue = errors.New("encrypted value is not valid")
)

// decodeKey decodes the provided base64-encoded key and validates its length.
// It returns the decoded key bytes or an error when invalid.
func decodeKey(key string) ([]byte, error) {
	keyDecoded, err := base64.StdEncoding.DecodeString(key)
	if err != nil {
		return nil, fmt.Errorf("failed to base64-decode key: %w", err)
	}

	keyLen := len(keyDecoded)
	if keyLen != 16 && keyLen != 24 && keyLen != 32 {
		return nil, ErrInvalidKeyLength
	}

	return keyDecoded, nil
}

View on GitHub (pinned to a105acad6c)