jackc/pgx · error

Upper cannot be NULL unless UpperType is Unbounded

Error message

Upper cannot be NULL unless UpperType is Unbounded

What it means

The range's upper bound is bounded (Inclusive or Exclusive) but the value returned for it is nil. The binary format reserves NULL encoding only for unbounded bounds, so the caller's RangeValuer state is inconsistent.

Solutions

1. Set UpperType to Unbounded when the upper value is absent
2. Supply a non-nil upper bound for bounded ranges
3. Use pgtype.Range[T] to maintain consistent bound state

When it happens

Trigger: Thrown at pgtype/range_codec.go:134 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/1ab6effb9d9c18a8. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/range_codec.go:134

		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 {
			return nil, fmt.Errorf("cannot encode %v as element of range", upper)
		}

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

View on GitHub (pinned to ec1a0befd2)