{"record":{"id":"b186287335b646ab","repo":"go-gorm/gorm","slug":"failed-to-parse-field-s-error-w","errorCode":null,"errorMessage":"failed to parse field: %s, error: %w","messagePattern":"failed to parse field: (.+?), error: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"schema/relationship.go","lineNumber":79,"sourceCode":"\tForeignKey    *Field\n\tOwnPrimaryKey bool\n}\n\nfunc (schema *Schema) parseRelation(field *Field) *Relationship {\n\tvar (\n\t\terr        error\n\t\tfieldValue = reflect.New(field.IndirectFieldType).Interface()\n\t\trelation   = &Relationship{\n\t\t\tName:        field.Name,\n\t\t\tField:       field,\n\t\t\tSchema:      schema,\n\t\t\tforeignKeys: toColumns(field.TagSettings[\"FOREIGNKEY\"]),\n\t\t\tprimaryKeys: toColumns(field.TagSettings[\"REFERENCES\"]),\n\t\t}\n\t)\n\n\tif relation.FieldSchema, err = getOrParse(fieldValue, schema.cacheStore, schema.namer); err != nil {\n\t\tschema.err = fmt.Errorf(\"failed to parse field: %s, error: %w\", field.Name, err)\n\t\treturn nil\n\t}\n\n\tif hasPolymorphicRelation(field.TagSettings) {\n\t\tschema.buildPolymorphicRelation(relation, field)\n\t} else if many2many := field.TagSettings[\"MANY2MANY\"]; many2many != \"\" {\n\t\tschema.buildMany2ManyRelation(relation, field, many2many)\n\t} else if belongsTo := field.TagSettings[\"BELONGSTO\"]; belongsTo != \"\" {\n\t\tschema.guessRelation(relation, field, guessBelongs)\n\t} else {\n\t\tswitch field.IndirectFieldType.Kind() {\n\t\tcase reflect.Struct:\n\t\t\tschema.guessRelation(relation, field, guessGuess)\n\t\tcase reflect.Slice:\n\t\t\tschema.guessRelation(relation, field, guessHas)\n\t\tdefault:\n\t\t\tschema.err = fmt.Errorf(\"unsupported data type %v for %v on field %s\", relation.FieldSchema, schema,\n\t\t\t\tfield.Name)","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/go-gorm/gorm/blob/1d6ce99528060be18a42be09aca8d39efcb47f28/schema/relationship.go#L61-L97","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ntype Order struct {\n    ID   uint\n    Meta map[string]any // unparseable, causes relation parse failure\n}\n\n// after\ntype Order struct {\n    ID   uint\n    Meta map[string]any `gorm:\"serializer:json\"`\n}","handlingStrategy":"try-catch","validationCode":"// Pre-flight parse before opening/using the DB\nif _, err := schema.Parse(&Order{}, &sync.Map{}, schema.NamingStrategy{}); err != nil {\n    log.Fatalf(\"model schema invalid: %v\", err)\n}","typeGuard":null,"tryCatchPattern":"err := db.AutoMigrate(&Order{})\nif err != nil {\n    var inner = errors.Unwrap(err)\n    for inner != nil { // surface deepest cause\n        if _, ok := inner.(interface{ Unwrap() error }); !ok { break }\n        inner = errors.Unwrap(inner)\n    }\n    return fmt.Errorf(\"migration failed (root cause: %v): %w\", inner, err)\n}","preventionTips":["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."],"tags":["gorm","schema","relation","reflection"],"backgroundTag":null,"analyzedSha":"1d6ce99528060be18a42be09aca8d39efcb47f28","analyzedAt":"2026-08-15T13:01:23.433Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}