jackc/pgx · error

failed to scan multirange element

Error message

failed to scan multirange element %d: %w

What it means

During binary multirange decoding, after element i's bytes are extracted they are passed to the element's own scan plan. This wrapper fires when that nested scan fails, wrapping the element-level error with the failing element's index so the offending member can be identified.

Solutions

1. Inspect the wrapped error to find the underlying element scan failure
2. Verify the multirange's element type matches the registered range subtype
3. Fix the destination element type to match the column's range subtype

When it happens

Trigger: Thrown at pgtype/multirange.go:237 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/0605f9331e2d162b. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/multirange.go:237

	if elementCount == 0 {
		return r.Finish()
	}

	elementScanPlan := c.ElementType.Codec.PlanScan(m, c.ElementType.OID, BinaryFormatCode, multirange.ScanIndex(0))
	if elementScanPlan == nil {
		elementScanPlan = m.PlanScan(c.ElementType.OID, BinaryFormatCode, multirange.ScanIndex(0))
	}

	for i := range elementCount {
		elem := multirange.ScanIndex(i)
		elemSrc, _ := r.Value()
		if err := r.Err(); err != nil {
			return fmt.Errorf("multirange element %d: %w", i, err)
		}
		err = elementScanPlan.Scan(elemSrc, elem)
		if err != nil {
			return fmt.Errorf("failed to scan multirange element %d: %w", i, err)
		}
	}

	return r.Finish()
}

func (c *MultirangeCodec) decodeText(m *Map, multirangeOID uint32, src []byte, multirange MultirangeSetter) error {
	elements, err := parseUntypedTextMultirange(src)
	if err != nil {
		return err
	}

	err = multirange.SetLen(len(elements))
	if err != nil {
		return err
	}

	if len(elements) == 0 {

View on GitHub (pinned to ec1a0befd2)