jackc/pgx · error

invalid hex format

Error message

invalid hex format

What it means

Returned by decodeHexBytea when the bytea text value does not start with the '\x' prefix. PostgreSQL bytea output in hex format always begins with \x; anything else (e.g. legacy escape format) is rejected before hex decoding.

Solutions

1. Ensure the server bytea_output setting is 'hex' (the default since PostgreSQL 9)
2. Hex-decode legacy escape-format data manually if needed

When it happens

Trigger: Thrown at pgtype/bytea.go:227 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/b4418eac3e6c037c. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/bytea.go:227

type scanPlanTextByteaToBytesScanner struct{}

func (scanPlanTextByteaToBytesScanner) Scan(src []byte, dst any) error {
	scanner := (dst).(BytesScanner)
	buf, err := decodeHexBytea(src)
	if err != nil {
		return err
	}
	return scanner.ScanBytes(buf)
}

func decodeHexBytea(src []byte) ([]byte, error) {
	if src == nil {
		return nil, nil
	}

	if len(src) < 2 || src[0] != '\\' || src[1] != 'x' {
		return nil, fmt.Errorf("invalid hex format")
	}

	buf := make([]byte, (len(src)-2)/2)
	_, err := hex.Decode(buf, src[2:])
	if err != nil {
		return nil, err
	}

	return buf, nil
}

func (c ByteaCodec) DecodeDatabaseSQLValue(m *Map, oid uint32, format int16, src []byte) (driver.Value, error) {
	return c.DecodeValue(m, oid, format, src)
}

func (c ByteaCodec) DecodeValue(m *Map, oid uint32, format int16, src []byte) (any, error) {
	if src == nil {
		return nil, nil

View on GitHub (pinned to ec1a0befd2)