ory/hydra · error
cookiex: cannot encode legacy cookie
Error message
cookiex: cannot encode legacy cookie
What it means
sealLegacy delegates the actual encryption/signing to securecookie.EncodeMulti with the first legacy codec. If that low-level encoding fails (bad key, value too large, serialization error), the error is wrapped with this message.
Source
Thrown at oryx/cookiex/legacy_securecookie.go:133
func (c *Codec[T]) sealLegacy(name string, value T) (string, error) {
buf, err := json.Marshal(value)
if err != nil {
return "", errors.Wrap(err, "cookiex: cannot marshal cookie value")
}
var flat map[string]string
if err := json.Unmarshal(buf, &flat); err != nil {
return "", errors.Wrap(err, "cookiex: payload must be a flat JSON object with string values while legacy encode is enabled")
}
if flat == nil {
return "", errors.New("cookiex: payload must be a flat JSON object with string values while legacy encode is enabled")
}
values := make(map[any]any, len(flat))
for k, v := range flat {
values[k] = v
}
encoded, err := securecookie.EncodeMulti(name, values, c.legacy.codecs[0])
if err != nil {
return "", errors.Wrap(err, "cookiex: cannot encode legacy cookie")
}
return encoded, nil
}
View on GitHub (pinned to 4174065ffb)
Solutions
- Verify the legacy securecookie codec is initialized with valid hashKey and blockKey (correct lengths: 32/64 bytes hash, 16/24/32 bytes block).
- Reduce cookie payload size so the encoded value fits within the ~4KB cookie limit.
- Confirm c.legacy.codecs[0] exists before sealing; guard against an empty codec list.
Example fix
// before
legacy.codecs = securecookie.Codecs{} // empty, no keys configured
// after
legacy.codecs = securecookie.Codecs{securecookie.New([]byte(hashKey32bytes), []byte(blockKey32bytes))} Defensive patterns
Strategy: try-catch
Validate before calling
if len(c.legacy.codecs) == 0 {
return errors.New("cookiex: legacy codecs not initialized")
} Try / catch
encoded, err := cookiex.Set(w, name, value)
if err != nil {
var e *errors.Error
if stderrors.As(err, &e) && strings.Contains(e.Error(), "cannot encode legacy cookie") {
log.Printf("legacy cookie encode failed (check keys/payload size): %v", err)
// fall back to modern codec or return 500
}
} Prevention
- Validate hash/block key lengths at startup (hash 32 or 64 bytes; block 16/24/32).
- Keep encoded cookie size under ~4KB; split or minimize payload.
- Log securecookie's underlying error, not just the wrapper.
When it happens
Trigger: Calling Set with legacy encode enabled when securecookie.EncodeMulti fails: misconfigured/expired legacy codec keys, an empty codec list, or a value that securecookie cannot serialize (e.g. exceeding size or containing unsupported types).
Common situations: Rotating or deleting cookie hash/block keys so the legacy codec has invalid keys; cookie payload exceeding the 4KB browser limit after encoding; legacy codecs never initialized.
Related errors
AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03).
Data as JSON: /api/errors/58dac1915119919b.
Report an issue: GitHub.