jackc/pgx · error

failed to scan array element

Error message

failed to scan array element %d: %w

What it means

The element codec's Scan returned an error for binary array element %d; the array framing was fine but the element value could not be decoded into the target (e.g. range overflow or invalid element data).

Solutions

1. Inspect the wrapped element error to identify the failing value and index
2. Widen the Go element type (e.g. []int64 instead of []int8) to fit the data
3. Fix the stored data or query so element values fit the scan target

When it happens

Trigger: Thrown at pgtype/array_codec.go:300 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/d300c85d1ebd3cf1. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/array_codec.go:300

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

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

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

	return r.Finish()
}

func (c *ArrayCodec) decodeText(m *Map, arrayOID uint32, src []byte, array ArraySetter) error {
	uta, err := parseUntypedTextArray(string(src))
	if err != nil {
		return err
	}

	// The element loop below indexes the value sized by SetDimensions, so the
	// dimensions and the parsed elements must agree.
	if elementCount := cardinality(uta.Dimensions); elementCount != len(uta.Elements) {
		return fmt.Errorf("array dimensions describe %d elements but %d were parsed", elementCount, len(uta.Elements))
	}

View on GitHub (pinned to ec1a0befd2)