jackc/pgx · error

unknown protocol representation

Error message

unknown protocol representation

What it means

getValueFromJSON guard: a protocol message was represented as a JSON object whose keys are neither "text" nor "binary" (hex). Only those two representations are understood when unmarshaling pgproto3 messages from JSON, so the unrecognized key set is the faulty input. Typically hit in tests or tooling that feed JSON to UnmarshalJSON.

Solutions

1. Represent the message body as {"text": "..."} or {"binary": "<hex>"}
2. Remove extra/misspelled keys from the JSON payload

When it happens

Trigger: Thrown at pgproto3/pgproto3.go:99 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/7cc6419c1d938dc4. Report an issue: GitHub.

Appendix: source

Thrown at pgproto3/pgproto3.go:99

	ActualBodyLen      int
}

func (e *ExceededMaxBodyLenErr) Error() string {
	return fmt.Sprintf("invalid body length: expected at most %d, but got %d", e.MaxExpectedBodyLen, e.ActualBodyLen)
}

// getValueFromJSON gets the value from a protocol message representation in JSON.
func getValueFromJSON(v map[string]string) ([]byte, error) {
	if v == nil {
		return nil, nil
	}
	if text, ok := v["text"]; ok {
		return []byte(text), nil
	}
	if binary, ok := v["binary"]; ok {
		return hex.DecodeString(binary)
	}
	return nil, errors.New("unknown protocol representation")
}

// beginMessage begins a new message of type t. It appends the message type and a placeholder for the message length to
// dst. It returns the new buffer and the position of the message length placeholder.
func beginMessage(dst []byte, t byte) ([]byte, int) {
	dst = append(dst, t)
	sp := len(dst)
	dst = pgio.AppendInt32(dst, -1)
	return dst, sp
}

// finishMessage finishes a message that was started with beginMessage. It computes the message length and writes it to
// dst[sp]. If the message length is too large it returns an error. Otherwise it returns the final message buffer.
func finishMessage(dst []byte, sp int) ([]byte, error) {
	messageBodyLen := len(dst[sp:])
	if messageBodyLen > maxMessageBodyLen {
		return nil, errors.New("message body too large")
	}

View on GitHub (pinned to ec1a0befd2)