jackc/pgx · error

unknown jsonb version number

Error message

unknown jsonb version number %d

What it means

PostgreSQL's binary jsonb wire format starts with a version byte that must currently be 1. This guard fires when that leading byte holds any other value, meaning the payload either is not binary jsonb or comes from an incompatible/unknown future version of the format.

Solutions

1. Confirm the column type is jsonb and the value was not mangled in transit
2. Use text format for jsonb columns if interoperability with the server's binary encoding is broken
3. Upgrade pgx to a version matching the server's PostgreSQL release

When it happens

Trigger: Thrown at pgtype/jsonb.go:72 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/579c0d26a85370c8. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/jsonb.go:72

	return nil
}

type scanPlanJSONBCodecBinaryUnwrapper struct {
	textPlan ScanPlan
}

func (plan *scanPlanJSONBCodecBinaryUnwrapper) Scan(src []byte, dst any) error {
	if src == nil {
		return plan.textPlan.Scan(src, dst)
	}

	if len(src) == 0 {
		return fmt.Errorf("jsonb too short")
	}

	if src[0] != 1 {
		return fmt.Errorf("unknown jsonb version number %d", src[0])
	}

	return plan.textPlan.Scan(src[1:], dst)
}

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

	switch format {
	case BinaryFormatCode:
		if len(src) == 0 {
			return nil, fmt.Errorf("jsonb too short")
		}

		if src[0] != 1 {
			return nil, fmt.Errorf("unknown jsonb version number %d", src[0])

View on GitHub (pinned to ec1a0befd2)