gofiber/fiber · critical

failed to base64-decode key: %w

Error message

failed to base64-decode key: %w

What it means

Thrown at middleware/encryptcookie/utils.go:23 inside decodeKey() when base64.StdEncoding.DecodeString(key) fails for the configured encryption key. The middleware requires the Key to be base64 (standard encoding) of 16, 24, or 32 raw bytes; any deviation in encoding, padding, or alphabet triggers this before any crypto runs.

Source

Thrown at middleware/encryptcookie/utils.go:23

	"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
}

// validateKey checks if the provided base64-encoded key is of valid length.
func validateKey(key string) error {
	_, err := decodeKey(key)
	return err
}

// EncryptCookie Encrypts a cookie value with specific encryption key
func EncryptCookie(name, value, key string) (string, error) {

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Generate the key with encryptcookie.GenerateKey(16|24|32) which returns valid standard-base64 and use that exact string verbatim.
2. If you already have raw key bytes, encode them yourself with base64.StdEncoding.EncodeToString(rawKey) before passing as Key.
3. Trim stray whitespace/newlines from the key before passing it (e.g. strings.TrimSpace on the env var).
4. If your key is URL-safe base64, re-encode it to standard base64 or translate -/_ to +//.
5. Call encryptcookie.ValidateKey(key) at startup to fail fast with a clear message instead of at the first request.

Example fix

// before: raw passphrase fails base64 decode
key := "my-secret-passphrase" // not base64 -> error 157
app.Use(encryptcookie.New(encryptcookie.Config{ Key: key }))

// after: generate once, store the base64 string in secrets
// key := encryptcookie.GenerateKey(32) // run once, persist output
key := os.Getenv("COOKIE_KEY") // e.g. "gm...k=" from GenerateKey
if err := encryptcookie.ValidateKey(key); err != nil {
    log.Fatalf("bad cookie key: %v", err)
}
app.Use(encryptcookie.New(encryptcookie.Config{ Key: strings.TrimSpace(key) }))

// Fail fast at startup: validate key encoding and length before serving traffic.
key := strings.TrimSpace(os.Getenv("COOKIE_ENCRYPTION_KEY"))
if err := encryptcookie.ValidateKey(key); err != nil {
    log.Fatalf("invalid cookie encryption key: %v", err)
}
app.Use(encryptcookie.New(encryptcookie.Config{ Key: key }))

// Confirm the key is well-formed standard base64 of an AES-compatible length.
func isValidCookieKey(s string) bool {
    raw, err := base64.StdEncoding.DecodeString(s)
    if err != nil { return false }
    switch len(raw) {
    case 16, 24, 32: return true
    }
    return false
}

enc, err := encryptcookie.EncryptCookie(name, value, key)
if err != nil {
    if strings.Contains(err.Error(), "base64-decode key") {
        // config bug - fail loudly, do not serve requests with a bad key
        log.Fatalf("cookie key is not valid base64; regenerate with encryptcookie.GenerateKey")
    }
    return err
}

When it happens

Trigger: EncryptCookie or DecryptCookie is called with a Key that is not valid standard-base64: a raw-ASCII key, a hex-encoded key, a URL-safe-base64 (- and _ instead of + and /) key, missing/wrong padding, or a key with stray whitespace/newlines.

Common situations: Operator set COOKIE_ENCRYPTION_KEY to a raw passphrase instead of GenerateKey output; CI/CD injected the key via an env var that trimmed padding or translated characters; key was generated with base64.URLEncoding instead of StdEncoding; copy-paste introduced a newline.

Related errors

• failed to create AES cipher: %w
• failed to create GCM mode: %w
• failed to base64-decode value: %w
• min constraint requires an argument
• max constraint requires an argument

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