JuliusBrussee/caveman · error
kms: decode envelope
Error message
kms: decode envelope: %w
What it means
Decrypt unmarshals the JSON that follows the envelope prefix in the blob; a json.Unmarshal failure is wrapped as "kms: decode envelope: %w". It indicates the ciphertext blob is not a valid JSON envelope after prefix stripping — typically corruption, truncation, or a blob produced by a different tool/version.
Solutions
- Verify the blob starts with the expected prefix and the remainder is valid JSON (json.Valid on the slice after the prefix).
- Re-encrypt the data — the original envelope is unrecoverable if the bytes are truly corrupted.
- Check the storage/transport path (encoding, column charset, file truncation) that delivered the blob.
- Confirm the blob was produced by this library's Encrypt and not another tool.
Example fix
// before
dec, err := kms.Decrypt(ctx, blob) // kms: decode envelope: invalid character...
// after
if !bytes.HasPrefix(blob, prefix) || !json.Valid(blob[len(prefix):]) {
return fmt.Errorf("malformed kms envelope (len=%d)", len(blob))
}
dec, err := kms.Decrypt(ctx, blob) Defensive patterns
Strategy: validation
Validate before calling
if !bytes.HasPrefix(blob, kmsPrefix) || len(blob) <= len(kmsPrefix) || !json.Valid(blob[len(kmsPrefix):]) {
return errors.New("blob is not a valid kms envelope")
} Type guard
func isKMSEnvelope(blob []byte) bool {
return bytes.HasPrefix(blob, prefix) && json.Valid(blob[len(prefix):])
} Try / catch
dec, err := kms.Decrypt(ctx, blob)
if err != nil {
if strings.Contains(err.Error(), "decode envelope") {
return fmt.Errorf("corrupt or foreign envelope (len=%d): %w", len(blob), err)
}
return err
} Prevention
- Store envelopes in binary-safe columns (bytea/blob), not text with charset transforms.
- Never round-trip envelopes through encodings that alter bytes (lossy base64, JSON string escapes).
- Version-stamp envelopes and validate format before Decrypt.
- Fail fast on truncated reads (compare stored length vs read length).
When it happens
Trigger: Calling Decrypt with a blob whose post-prefix bytes are not valid JSON: truncated storage, base64/text encoding mangled the bytes, wrong prefix handling, or an envelope written by another KMS format.
Common situations: Storing envelopes in a DB column that strips padding or re-encodes; copy-pasting an envelope through a medium that alters characters; reading a partial write after a crash; mixing envelope formats across library versions.
Related errors
AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20).
Data as JSON: /api/errors/d12e1027d10e14d2.
Report an issue: GitHub.
Appendix: source
Thrown at shared/platform/kms/kms.go:231
client, err := FromPayloadEnvironment()
if err != nil {
return nil, err
}
return client.Decrypt(ctx, blob)
}
// Decrypt unwraps versioned KMS envelope. Metadata can choose only validated
// key identity under configured provider; it can never choose host or token.
func (c *Client) Decrypt(ctx context.Context, blob []byte) ([]byte, error) {
if !IsEnvelope(blob) {
return nil, errors.New("kms: unknown envelope format")
}
if len(blob) > maxEnvelopeBytes {
return nil, errors.New("kms: envelope exceeds size limit")
}
var envelope Envelope
if err := json.Unmarshal(blob[len(prefix):], &envelope); err != nil {
return nil, fmt.Errorf("kms: decode envelope: %w", err)
}
if envelope.Provider != c.provider {
return nil, errors.New("kms: envelope provider does not match configured provider")
}
if err := validateLocation(envelope.Region, envelope.KeyID); err != nil {
return nil, err
}
if envelope.Region != c.region {
return nil, errors.New("kms: envelope region is not approved")
}
if _, ok := c.decryptKeyIDs[envelope.KeyID]; !ok {
return nil, errors.New("kms: envelope key ID is not approved")
}
if strings.TrimSpace(envelope.Ciphertext) == "" {
return nil, errors.New("kms: envelope ciphertext is empty")
}
var response struct {
KeyID string `json:"key_id"`View on GitHub (pinned to 3ee70a1026)