jackc/pgx · error

%#v only has public fields - is out of bounds

Error message

%#v only has %d public fields - %d is out of bounds

What it means

structWrapper.Index was asked for a composite field index beyond the number of exported (public) fields the struct actually has. The out-of-range index comes from a PostgreSQL composite/record type with more fields than the Go struct's exported fields.

Solutions

1. Add exported fields to the struct so it matches the composite type's field count
2. Reorder so unexported fields are not counted; only public fields are scannable
3. Scan into pgtype.CompositeFields for a dynamic field count

When it happens

Trigger: Thrown at pgtype/builtin_wrappers.go:723 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/a5cba5fae6b1c7dc. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/builtin_wrappers.go:723

	uuid := UUID{Valid: true}
	copy(uuid.Bytes[:], w)
	return uuid, nil
}

// structWrapper implements CompositeIndexGetter for a struct.
type structWrapper struct {
	s              any
	exportedFields []reflect.Value
}

func (w structWrapper) IsNull() bool {
	return w.s == nil
}

func (w structWrapper) Index(i int) any {
	if i >= len(w.exportedFields) {
		return fmt.Errorf("%#v only has %d public fields - %d is out of bounds", w.s, len(w.exportedFields), i)
	}

	return w.exportedFields[i].Interface()
}

// ptrStructWrapper implements CompositeIndexScanner for a pointer to a struct.
type ptrStructWrapper struct {
	s              any
	exportedFields []reflect.Value
}

func (w *ptrStructWrapper) ScanNull() error {
	return fmt.Errorf("cannot scan NULL into %#v", w.s)
}

func (w *ptrStructWrapper) ScanIndex(i int) any {
	if i >= len(w.exportedFields) {
		return fmt.Errorf("%#v only has %d public fields - %d is out of bounds", w.s, len(w.exportedFields), i)

View on GitHub (pinned to ec1a0befd2)