gofiber/fiber · error

failed to base64-decode key

Error message

failed to base64-decode key: %w

What it means

Returned by decodeKey when base64.StdEncoding.DecodeString fails on the configured EncryptCookie/DecryptCookie key. The key must be valid standard base64 that decodes to 16, 24, or 32 bytes; this error fires before the length check, meaning the input is not valid base64 at all.

Solutions

1. Generate the key with encryptcookie.GenerateKey(16|24|32) — its output is valid StdEncoding base64.
2. If the key came from an external source, re-encode it: base64.StdEncoding.EncodeToString([]byte(rawKey)).
3. Strip whitespace/newlines from env-var-sourced keys before use.
4. If the source is URL-safe base64, translate it to standard first: base64.StdEncoding.EncodeToString(base64.URLEncoding.DecodeString(key)).

Example fix

// before: raw ASCII key — not base64
app.Use(encryptcookie.New(encryptcookie.Config{
    Key: "mysecretkey12345", // fails base64 decode
}))

// after: generate a valid key (run once, store the output)
key := encryptcookie.GenerateKey(32) // valid StdEncoding base64
app.Use(encryptcookie.New(encryptcookie.Config{Key: key}))

// Validate the key BEFORE wiring it into the middleware.
func validateEncryptKey(key string) error {
    dec, err := base64.StdEncoding.DecodeString(key)
    if err != nil {
        return fmt.Errorf("key is not valid standard base64: %w", err)
    }
    if len(dec) != 16 && len(dec) != 24 && len(dec) != 32 {
        return encryptcookie.ErrInvalidKeyLength
    }
    return nil
}

// at startup
if err := validateEncryptKey(os.Getenv("COOKIE_KEY")); err != nil {
    log.Fatal(err)
}

// Prefer the middleware's own validation at boot over per-request handling.
// encryptcookie.New calls validateKey via config; ensure Key is set from a
// trusted generated value.
key := encryptcookie.GenerateKey(32)
app.Use(encryptcookie.New(encryptcookie.Config{Key: key}))

When it happens

Trigger: EncryptCookie or DecryptCookie is called (directly or via the encryptcookie middleware) with a Key that is not valid standard-base64: contains URL-safe characters (-/_), has wrong padding, includes whitespace/newlines, or is raw hex/ASCII rather than base64.

Common situations: Passing a raw ASCII string instead of a base64-encoded key; using base64.URLEncoding output as a key (it contains - and _ which StdEncoding rejects); trailing newline in a key read from an env var or file; using GenerateKey's output correctly but then editing it; copy-paste truncation.

Related errors

• failed to create AES cipher
• encryption key must be 16, 24, or 32 bytes
• cache: failed to delete key
• cache: failed to delete raw key
• cache: failed to get key

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

Appendix: 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 a105acad6c)