jackc/pgx · error

failed to encode as element of range

Error message

failed to encode %v as element of range: %w

What it means

The lower bound's own encoder ran and returned an error; the range encoder wraps it with the offending value to show which element failed. The root cause is in the element-type encoding, the range just propagates it.

Solutions

1. Inspect the wrapped error to find the element encoding failure (e.g. out-of-range value, bad format)
2. Fix or sanitize the bound value to satisfy the element codec
3. Validate element values before putting them in the range

When it happens

Trigger: Thrown at pgtype/range_codec.go:123 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/9b974d85205c19c8. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/range_codec.go:123

	buf = append(buf, rangeType)

	if lowerType != Unbounded {
		if lower == nil {
			return nil, fmt.Errorf("Lower cannot be NULL unless LowerType is Unbounded")
		}

		sp := len(buf)
		buf = pgio.AppendInt32(buf, -1)

		lowerPlan := plan.m.PlanEncode(plan.rc.ElementType.OID, BinaryFormatCode, lower)
		if lowerPlan == nil {
			return nil, fmt.Errorf("cannot encode %v as element of range", lower)
		}

		buf, err = lowerPlan.Encode(lower, buf)
		if err != nil {
			return nil, fmt.Errorf("failed to encode %v as element of range: %w", lower, err)
		}
		if buf == nil {
			return nil, fmt.Errorf("Lower cannot be NULL unless LowerType is Unbounded")
		}

		pgio.SetInt32(buf[sp:], int32(len(buf[sp:])-4))
	}

	if upperType != Unbounded {
		if upper == nil {
			return nil, fmt.Errorf("Upper cannot be NULL unless UpperType is Unbounded")
		}

		sp := len(buf)
		buf = pgio.AppendInt32(buf, -1)

		upperPlan := plan.m.PlanEncode(plan.rc.ElementType.OID, BinaryFormatCode, upper)
		if upperPlan == nil {

View on GitHub (pinned to ec1a0befd2)