What causes "missing field" in jmoiron/sqlx?

Add the missing column to the struct (exported field, correct `db:"column_name"` tag).

missing field

Error message

missing field

What it means

missingFields iterates over reflectx traversals (column-to-field index paths) and fires when any traversal is empty, meaning a returned column could not be matched to a field in the destination struct. sqlx refuses to scan rows where columns lack a corresponding exported struct field, so partial/ambiguous mapping fails loudly instead of silently dropping data.

Source

Thrown at sqlx.go:1050

	for i, traversal := range traversals {
		if len(traversal) == 0 {
			values[i] = new(interface{})
			continue
		}
		f := reflectx.FieldByIndexes(v, traversal)
		if ptrs {
			values[i] = f.Addr().Interface()
		} else {
			values[i] = f.Interface()
		}
	}
	return nil
}

func missingFields(transversals [][]int) (field int, err error) {
	for i, t := range transversals {
		if len(t) == 0 {
			return i, errors.New("missing field")
		}
	}
	return 0, nil
}

View on GitHub (pinned to 41dac167fd)

Solutions

Add the missing column to the struct (exported field, correct `db:"column_name"` tag).
Restrict the SELECT to only the columns the struct defines.
Ensure the field is exported and its `db` tag matches the column name exactly.
Customize the mapper (sqlx.NameMapper / db.Mapper) if naming conventions differ.

Example fix

// before
type User struct {
    Name string `db:"name"`
}
// SELECT id, name FROM users -> "missing field"
// after
type User struct {
    ID   int    `db:"id"`
    Name string `db:"name"`
}

Defensive patterns

Strategy: validation

Validate before calling

cols, _ := rows.Columns()
for _, c := range cols {
	if !structHasField(MyStruct{}, c) {
		log.Printf("column %q has no struct field", c)
	}
}

Try / catch

if err := rows.StructScan(&dest); err != nil {
	if strings.HasPrefix(err.Error(), "missing field") {
		// log rows.Columns() vs struct db tags and align them
	}
	return err
}

Prevention

Keep SELECT column lists explicit and matched to struct fields.
Add `db:"column_name"` tags to every scanned field.
Run a startup smoke test that StructScans one row per query.
Re-sync struct definitions when the schema migrates.
Use SELECT * only with structs that mirror the whole table.

When it happens

Trigger: StructScan/Get/Select with a query returning a column whose name (after db tag mapping) matches no field of the destination struct — e.g. column `user_id` with no `user_id`/`userID` field or `db:"user_id"` tag.

Common situations: Schema changed to add a column the struct does not have; SELECT * returning extra columns; missing or misspelled `db` struct tags; unexported fields (cannot be mapped); column-name case mismatches with default MapperFunc (lowercase).

Related errors

AI-assisted analysis of jmoiron/sqlx@41dac167fd (2026-09-03). Data as JSON: /api/errors/ba788a20ce196993. Report an issue: GitHub.