crowdsecurity/crowdsec · error

ErrCookieVersion

ErrCookieVersion

Error message

%w: 0x%02x

What it means

The first byte of a decoded challenge cookie is not a known envelope version (only cookieVersionV0 exists). ErrCookieVersion is wrapped with the offending version byte in hex. This is expected when a cookie issued by a future/other deployment (or garbage) is presented; the client is re-challenged rather than trusted.

Source

Thrown at pkg/appsec/challenge/crypto.go:210

	}

	if len(encoded) > maxCookieLen {
		return nil, fmt.Errorf("%w: %d > %d", ErrCookieTooLarge, len(encoded), maxCookieLen)
	}

	raw, err := base64.RawURLEncoding.DecodeString(encoded)
	if err != nil {
		return nil, fmt.Errorf("%w: failed to decode: %w", ErrCookieMalformed, err)
	}
	if len(raw) < 1 {
		return nil, fmt.Errorf("%w: empty cookie", ErrCookieMalformed)
	}

	switch raw[0] {
	case cookieVersionV0:
		return openCookieV0Bytes(raw[1:], masterCookieKey, aad, time.Now())
	default:
		return nil, fmt.Errorf("%w: 0x%02x", ErrCookieVersion, raw[0])
	}
}

func openCookieV0Bytes(body []byte, masterCookieKey []byte, aad []byte, now time.Time) (*CookieEnvelope, error) {
	key, err := deriveKey(masterCookieKey)
	if err != nil {
		return nil, err
	}

	block, err := aes.NewCipher(key)
	if err != nil {
		return nil, fmt.Errorf("failed to create cipher: %w", err)
	}

	gcm, err := cipher.NewGCM(block)
	if err != nil {
		return nil, fmt.Errorf("failed to create GCM: %w", err)
	}

View on GitHub (pinned to 909b515798)

Solutions

1. Usually benign: stale cookies from an older/newer crowdsec deployment are rejected and re-issued
2. If persistent after an upgrade, let the old cookies expire or clear them client-side
3. Verify all nodes behind the bouncer run a compatible cookie version

When it happens

Trigger: Thrown at pkg/appsec/challenge/crypto.go:210 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of crowdsecurity/crowdsec@909b515798 (2026-09-06). Data as JSON: /api/errors/89f843575d495aaa. Report an issue: GitHub.