{"record":{"id":"7b581a460ee19706","repo":"go-gorm/gorm","slug":"s-unsupported-relations-for-schema-s","errorCode":null,"errorMessage":"%s: unsupported relations for schema %s","messagePattern":"(.+?): unsupported relations for schema (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"callbacks/preload.go","lineNumber":163,"sourceCode":"\t\t\t\tcase reflect.Struct, reflect.Pointer:\n\t\t\t\t\treflectValue := rel.Field.ReflectValueOf(db.Statement.Context, rv)\n\t\t\t\t\ttx := preloadDB(db, reflectValue, reflectValue.Interface())\n\t\t\t\t\tif err := preloadEntryPoint(tx, nestedJoins, &tx.Statement.Schema.Relationships, preloadMap[name], associationsConds); err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\tdefault:\n\t\t\t\t\treturn gorm.ErrInvalidData\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\ttx := db.Table(\"\").Session(&gorm.Session{Context: db.Statement.Context, SkipHooks: db.Statement.SkipHooks})\n\t\t\t\ttx.Statement.ReflectValue = db.Statement.ReflectValue\n\t\t\t\ttx.Statement.Unscoped = db.Statement.Unscoped\n\t\t\t\tif err := preload(tx, rel, append(preloads[name], associationsConds...), preloadMap[name]); err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t}\n\t\t} else {\n\t\t\treturn fmt.Errorf(\"%s: %w for schema %s\", name, gorm.ErrUnsupportedRelation, db.Statement.Schema.Name)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc preloadDB(db *gorm.DB, reflectValue reflect.Value, dest interface{}) *gorm.DB {\n\ttx := db.Session(&gorm.Session{Context: db.Statement.Context, NewDB: true, SkipHooks: db.Statement.SkipHooks, Initialized: true})\n\tdb.Statement.Settings.Range(func(k, v interface{}) bool {\n\t\ttx.Statement.Settings.Store(k, v)\n\t\treturn true\n\t})\n\n\tif err := tx.Statement.Parse(dest); err != nil {\n\t\ttx.AddError(err)\n\t\treturn tx\n\t}\n\ttx.Statement.ReflectValue = reflectValue\n\ttx.Statement.Unscoped = db.Statement.Unscoped","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/go-gorm/gorm/blob/1d6ce99528060be18a42be09aca8d39efcb47f28/callbacks/preload.go#L145-L181","documentation":"During Preload execution, each preload name must resolve to a relation on the statement's schema. When the name has no dot (not a nested path) and Relations[name] is nil, GORM returns fmt.Errorf(\"%s: %w for schema %s\", name, gorm.ErrUnsupportedRelation, db.Statement.Schema.Name) - i.e. '<name>: unsupported relations for schema <Schema>'.","triggerScenarios":"db.Preload(\"Ordrs\").Find(&users) with a typo; Preload(\"Name\") where Name is a plain column, not an association; a relation field tagged `gorm:\"-\"` or of a non-struct kind so it never enters Relationships.","commonSituations":"String-based preload names silently breaking after model refactors (compiler cannot catch them); copying preload chains between models where the relation does not exist; nested preload paths ('Company.Employees') where an intermediate segment is wrong.","solutions":["Match the preload name exactly to the relation's Go field name (case-sensitive).","Verify nested paths segment by segment (each must be a relation on the respective schema).","Define relation-name constants and reuse them in Preload calls.","Log db.Statement.Schema Relationships keys in a test that asserts every preload name resolves."],"exampleFix":"// before\ndb.Preload(\"Ordrs\").Find(&users)\n\n// after\ndb.Preload(\"Orders\").Find(&users)","handlingStrategy":"validation","validationCode":"func preloadNamesResolve(db *gorm.DB, model interface{}, names ...string) error {\n    stmt := &gorm.Statement{DB: db}\n    if err := stmt.Parse(model); err != nil { return err }\n    for _, n := range names {\n        cur := stmt.Schema\n        for _, seg := range strings.Split(n, \".\") {\n            r := cur.Relationships.Relations[seg]\n            if r == nil { return fmt.Errorf(\"preload %q: no relation %s on %s\", n, seg, cur.Name) }\n            cur = r.FieldSchema\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := db.Preload(\"Orders\").Find(&users).Error; err != nil {\n    if errors.Is(err, gorm.ErrUnsupportedRelation) {\n        return errors.New(\"preload name does not match a relation field\")\n    }\n    return err\n}","preventionTips":["Store preload names as constants defined beside the model.","Unit-test each query builder against schema.Parse to catch renames at CI time.","Remember names are Go field names, case-sensitive - not column or table names."],"tags":["gorm","preload","associations","typo","api-misuse"],"backgroundTag":null,"analyzedSha":"1d6ce99528060be18a42be09aca8d39efcb47f28","analyzedAt":"2026-08-15T13:01:23.433Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}