jackc/pgx · error

cannot find field in returned row

Error message

cannot find field %s in returned row

What it means

RowToStructByName (strict mode) found a row column with no matching struct field; the %s names the unmatched column. The lax variant (RowToStructByNameLax) suppresses exactly this error by ignoring extra columns.

Solutions

1. Add a struct field named after the column or tagged db:"<column>"
2. Switch to RowToStructByNameLax to tolerate extra columns
3. Alias the column in the SELECT to match an existing field

When it happens

Trigger: Thrown at rows.go:692 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/b4b8a2eacb6060aa. Report an issue: GitHub.

Appendix: source

Thrown at rows.go:692

	var value T
	err := (&namedStructRowScanner{ptrToStruct: &value, lax: true}).ScanRow(row)
	return &value, err
}

type namedStructRowScanner struct {
	ptrToStruct any
	lax         bool
}

func (rs *namedStructRowScanner) ScanRow(rows CollectableRow) error {
	typ := reflect.TypeOf(rs.ptrToStruct).Elem()
	fldDescs := rows.FieldDescriptions()
	namedStructFields, err := lookupNamedStructFields(typ, fldDescs)
	if err != nil {
		return err
	}
	if !rs.lax && namedStructFields.missingField != "" {
		return fmt.Errorf("cannot find field %s in returned row", namedStructFields.missingField)
	}
	fields := namedStructFields.fields
	scanTargets := setupStructScanTargets(rs.ptrToStruct, fields)
	return rows.Scan(scanTargets...)
}

// Map from namedStructFieldMap -> *namedStructFields
var namedStructFieldMap sync.Map

type namedStructFieldsKey struct {
	t        reflect.Type
	colNames string
}

type namedStructFields struct {
	fields []structRowField
	// missingField is the first field from the struct without a corresponding row field.
	// This is used to construct the correct error message for non-lax queries.

View on GitHub (pinned to ec1a0befd2)