golang/go · error

tls: unknown session encoding

Error message

tls: unknown session encoding

What it means

Returned by ParseSessionState (ticket.go:218) when the single-byte 'typ' field is neither 1 (server session) nor 2 (client session). The encoding scheme reserves exactly those two values; anything else means the blob was produced by an unknown/future encoder or is corrupt.

Source

Thrown at src/crypto/tls/ticket.go:218

		!s.ReadUint8(&earlyData) ||
		len(ss.secret) == 0 ||
		!unmarshalCertificate(&s, &cert) {
		return nil, errors.New("tls: invalid session encoding")
	}
	for !extra.Empty() {
		var e []byte
		if !readUint24LengthPrefixed(&extra, &e) {
			return nil, errors.New("tls: invalid session encoding")
		}
		ss.Extra = append(ss.Extra, e)
	}
	switch typ {
	case 1:
		ss.isClient = false
	case 2:
		ss.isClient = true
	default:
		return nil, errors.New("tls: unknown session encoding")
	}
	switch extMasterSecret {
	case 0:
		ss.extMasterSecret = false
	case 1:
		ss.extMasterSecret = true
	default:
		return nil, errors.New("tls: invalid session encoding")
	}
	switch earlyData {
	case 0:
		ss.EarlyData = false
	case 1:
		ss.EarlyData = true
	default:
		return nil, errors.New("tls: invalid session encoding")
	}
	for _, cert := range cert.Certificate {

View on GitHub (pinned to b6b368adc5)

Solutions

1. Treat as an unsupported/corrupt blob: drop it and do a full handshake.
2. Version-gate persisted session blobs and refuse blobs from newer Go versions.
3. Clear the session cache after upgrading or downgrading Go.

ss, err := tls.ParseSessionState(data)
if err != nil {
    // Unknown type byte means newer/foreign encoding. Drop and re-handshake.
    cache.Delete(key)
    return nil
}

When it happens

Trigger: Deserializing a session blob whose type byte is 0 or >=3. Happens when the blob was written by a newer Go that extended the type namespace, or when random/corrupt bytes happen to pass the earlier structural reads.

Common situations: Forward-incompatibility: reading a session state produced by a newer Go version that added a new type byte; cache pollution with non-session bytes; mismatched endianness when blobs were transferred between big-endian/little-endian stores.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• tls: invalid session encoding
• tls: server selected an invalid PSK
• tls: server selected an invalid PSK and cipher suite pair
• tls: session supported extended_master_secret but client doe
• tls: internal error: empty verified chain

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/3f9b93eb53f2efea. Report an issue: GitHub.