gofiber/fiber · critical · ErrInvalidKeyLength

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 encryptcookie.decodeKey (utils.go:28) when the base64-decoded key is not exactly 16, 24, or 32 bytes — the only valid AES key sizes (AES-128, AES-192, AES-256). The key is expected to be base64-encoded; after decoding, the raw byte length must match an AES key size. Both EncryptCookie and DecryptCookie call decodeKey first, so the error surfaces on the first encrypt/decrypt operation.

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 9a4c7e57fe)

Solutions

1. Generate a valid key with encryptcookie.GenerateKey(32) (AES-256) and use the returned base64 string as Config.Key.
2. If you have a raw key, base64-encode it and confirm it decodes to 16/24/32 bytes.
3. Load the key from an environment variable and validate it at startup with encryptcookie.ValidateKey(key) before the server starts.

Example fix

// before — raw string, wrong length
app.Use(encryptcookie.New(encryptcookie.Config{
  Key: "my-secret-key",
}))
// after — base64-encoded 32-byte key
key := encryptcookie.GenerateKey(32)
app.Use(encryptcookie.New(encryptcookie.Config{
  Key: key,
}))

// Validate the key at startup before serving traffic
key := os.Getenv("ENCRYPT_COOKIE_KEY")
if err := encryptcookie.ValidateKey(key); err != nil {
    log.Fatalf("invalid cookie encryption key: %v", err)
}

When it happens

Trigger: Configuring encryptcookie.Config.Key with a base64 string that decodes to a wrong length — e.g. a random 20-byte key, a raw ASCII string instead of base64-encoded bytes, or a truncated/padded value. GenerateKey(length) also panics with this error if given an invalid length.

Common situations: Pasting a plain text string as the key instead of base64-encoded bytes; generating a key with the wrong byte count; environment variable truncation; confusion between the base64 string length (e.g. 24 chars for 16 bytes) and the raw byte length; rotating keys and using a new value of the wrong size.

Related errors

• failed to create AES cipher: %w
• failed to create GCM mode: %w
• decode SHA256 password: invalid length
• failed to base64-decode key: %w
• failed to base64-decode value: %w

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/d43dbc9255f8b9fc.json. Report an issue: GitHub.