jackc/pgx · error

unsupported ltree version

Error message

unsupported ltree version %d

What it means

The binary ltree wire format prefixes its serialized label path with a one-byte version that must currently be 1. This guard fires when a non-NULL binary ltree payload begins with any other version byte — the payload is either not binary ltree or was encoded by an incompatible format version.

Solutions

1. Verify the column is an ltree type and the value wasn't mangled
2. Request text format for ltree columns if binary interoperation fails
3. Update pgx to match the server's ltree binary format version

When it happens

Trigger: Thrown at pgtype/ltree.go:93 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/6f3dd46455479236. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/ltree.go:93

		return (TextCodec)(l).PlanScan(m, oid, format, target)
	case BinaryFormatCode:
		switch target.(type) {
		case *string:
			return scanPlanBinaryLtreeToString{}
		case TextScanner:
			return scanPlanBinaryLtreeToTextScanner{}
		}
	}

	return nil
}

type scanPlanBinaryLtreeToString struct{}

func (scanPlanBinaryLtreeToString) Scan(src []byte, target any) error {
	version := src[0]
	if version != 1 {
		return fmt.Errorf("unsupported ltree version %d", version)
	}

	p := (target).(*string)
	*p = string(src[1:])

	return nil
}

type scanPlanBinaryLtreeToTextScanner struct{}

func (scanPlanBinaryLtreeToTextScanner) Scan(src []byte, target any) error {
	version := src[0]
	if version != 1 {
		return fmt.Errorf("unsupported ltree version %d", version)
	}

	scanner := (target).(TextScanner)
	return scanner.ScanText(Text{String: string(src[1:]), Valid: true})

View on GitHub (pinned to ec1a0befd2)