jackc/pgx · error

array dimensions describe

Error message

array dimensions describe %d elements but %d were parsed

What it means

Consistency guard after text array parsing in decodeText: cardinality(uta.Dimensions) disagrees with the number of parsed elements. The literal's declared dimensions describe a different element count than the '{...}' body actually contained (or the parse produced inconsistent brackets).

Solutions

1. Make the explicit dimension prefix match the number of elements in the body
2. Drop the explicit dimensions and let them be inferred from the braces
3. Regenerate the literal with a proper encoder instead of string building

When it happens

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

Appendix: source

Thrown at pgtype/array_codec.go:316

		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))
	}

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

	if len(uta.Elements) == 0 {
		return nil
	}

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

	for i, s := range uta.Elements {
		elem := array.ScanIndex(i)

View on GitHub (pinned to ec1a0befd2)