jackc/pgx · error

array claims elements but only bytes remain

Error message

array claims %d elements but only %d bytes remain

What it means

Binary array decode guard: the array header's dimensions claim more elements than could possibly fit in the remaining message bytes (each element needs at least a 4-byte length). This indicates a corrupt or malicious server response, and the check bounds allocations before SetDimensions.

Solutions

1. Treat the connection/data as untrusted and fail the query; do not retry the same payload
2. Check for a proxy or middleware corrupting binary results
3. Verify the server is a real PostgreSQL-compatible server sending well-formed binary arrays

When it happens

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

Appendix: source

Thrown at pgtype/array_codec.go:275

		oid:        oid,
		formatCode: format,
	}
}

func (c *ArrayCodec) decodeBinary(m *Map, arrayOID uint32, src []byte, array ArraySetter) error {
	r := pgio.NewReader(src)
	var arrayHeader arrayHeader
	err := arrayHeader.DecodeBinary(r)
	if err != nil {
		return err
	}

	elementCount := cardinality(arrayHeader.Dimensions)
	// Each element carries at minimum a 4-byte length header, so elementCount cannot exceed the
	// remaining bytes / 4. This bounds the allocation in SetDimensions and the loop below against a
	// malicious server claiming huge dimensions in a small message.
	if maxElements := r.Remaining() / 4; elementCount > maxElements {
		return fmt.Errorf("array claims %d elements but only %d bytes remain", elementCount, r.Remaining())
	}

	err = array.SetDimensions(arrayHeader.Dimensions)
	if err != nil {
		return err
	}

	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)

View on GitHub (pinned to ec1a0befd2)