What causes "failed to parse field: %s, error: %w" in go-gorm/gorm?

Read the wrapped error (`error: %w` part) — it names the real failing type inside the related struct; fix that type or its tags first.

go-gorm/gorm · error

failed to parse field: %s, error: %w

Error message

failed to parse field: %s, error: %w

What it means

GORM failed to parse the schema of a struct field's type while building a relationship. When a relation field (e.g. `Owner User`) is discovered, GORM recursively parses the related model via getOrParse; if that nested parse fails, the error is wrapped as 'failed to parse field: <FieldName>'. The root cause is almost always in the related struct (invalid data type, broken tag, or a deeper relation error), not the field named in the message.

Source

Thrown at schema/relationship.go:79

	ForeignKey    *Field
	OwnPrimaryKey bool
}

func (schema *Schema) parseRelation(field *Field) *Relationship {
	var (
		err        error
		fieldValue = reflect.New(field.IndirectFieldType).Interface()
		relation   = &Relationship{
			Name:        field.Name,
			Field:       field,
			Schema:      schema,
			foreignKeys: toColumns(field.TagSettings["FOREIGNKEY"]),
			primaryKeys: toColumns(field.TagSettings["REFERENCES"]),
		}
	)

	if relation.FieldSchema, err = getOrParse(fieldValue, schema.cacheStore, schema.namer); err != nil {
		schema.err = fmt.Errorf("failed to parse field: %s, error: %w", field.Name, err)
		return nil
	}

	if hasPolymorphicRelation(field.TagSettings) {
		schema.buildPolymorphicRelation(relation, field)
	} else if many2many := field.TagSettings["MANY2MANY"]; many2many != "" {
		schema.buildMany2ManyRelation(relation, field, many2many)
	} else if belongsTo := field.TagSettings["BELONGSTO"]; belongsTo != "" {
		schema.guessRelation(relation, field, guessBelongs)
	} else {
		switch field.IndirectFieldType.Kind() {
		case reflect.Struct:
			schema.guessRelation(relation, field, guessGuess)
		case reflect.Slice:
			schema.guessRelation(relation, field, guessHas)
		default:
			schema.err = fmt.Errorf("unsupported data type %v for %v on field %s", relation.FieldSchema, schema,
				field.Name)

View on GitHub (pinned to 1d6ce99528)

Solutions

Read the wrapped error (`error: %w` part) — it names the real failing type inside the related struct; fix that type or its tags first.
Ensure the field's type is either a valid GORM model (struct), a slice of models, or a scalar implementing driver.Valuer/sql.Scanner.
If the field is not meant to be persisted, add `gorm:"-"` to exclude it.
If the field holds serialized data, annotate it with `gorm:"serializer:json"` (or gob) so GORM does not try to parse it as a relation.

Example fix

// before
type Order struct {
    ID   uint
    Meta map[string]any // unparseable, causes relation parse failure
}

// after
type Order struct {
    ID   uint
    Meta map[string]any `gorm:"serializer:json"`
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight parse before opening/using the DB
if _, err := schema.Parse(&Order{}, &sync.Map{}, schema.NamingStrategy{}); err != nil {
    log.Fatalf("model schema invalid: %v", err)
}

Try / catch

err := db.AutoMigrate(&Order{})
if err != nil {
    var inner = errors.Unwrap(err)
    for inner != nil { // surface deepest cause
        if _, ok := inner.(interface{ Unwrap() error }); !ok { break }
        inner = errors.Unwrap(inner)
    }
    return fmt.Errorf("migration failed (root cause: %v): %w", inner, err)
}

Prevention

Run schema.Parse on all models in a unit test so relation errors surface at CI time, not at first query.
Never place DTO/config structs on models without gorm:"-" or a serializer tag.
Keep relation tags (foreignKey/references) pointing at real exported fields.

When it happens

Trigger: Declaring a relation field whose target struct itself cannot be parsed, e.g. `type Order struct { User User }` where User has a field of an unsupported kind (map, chan, func) or a malformed gorm tag. Also triggered when the related type is a non-struct, non-slice type such as `Data map[string]string` or a basic type GORM cannot turn into a schema.

Common situations: Adding a non-model helper struct (request DTO, config struct) as an embedded or direct field on a model; using custom types that don't implement Valuer/Scanner; typos in relation tags such as `gorm:"foreignKey:WrongName"`; circular self-references with invalid intermediate types after a refactor.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of go-gorm/gorm@1d6ce99528 (2026-08-15). Data as JSON: /api/errors/b186287335b646ab. Report an issue: GitHub.