{"record":{"id":"8b324b94128045a0","repo":"go-gorm/gorm","slug":"unsupported-relationship","errorCode":null,"errorMessage":"unsupported relationship","messagePattern":"unsupported relationship","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"generics.go","lineNumber":911,"sourceCode":"\t\tcase clause.OpUpdate:\n\t\t\t// Update related table rows that have join rows matching owners\n\t\t\trelatedDB := base.Session(&Session{NewDB: true, Context: ctx}).Table(rel.FieldSchema.Table).Where(op.Conditions)\n\n\t\t\t// correlated join subquery: join.rel_fk = related.pk AND EXISTS owners\n\t\t\tjoinSub := base.Session(&Session{NewDB: true, Context: ctx}).Table(rel.JoinTable.Table).Select(\"1\")\n\t\t\tfor _, ref := range rel.References {\n\t\t\t\tif !ref.OwnPrimaryKey && ref.PrimaryKey != nil {\n\t\t\t\t\tjoinSub = joinSub.Where(clause.Eq{\n\t\t\t\t\t\tColumn: clause.Column{Table: rel.JoinTable.Table, Name: ref.ForeignKey.DBName},\n\t\t\t\t\t\tValue:  clause.Column{Table: rel.FieldSchema.Table, Name: ref.PrimaryKey.DBName},\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t}\n\t\t\tjoinSub = joinSub.Where(\"EXISTS (?)\", ownersExists)\n\t\t\treturn relatedDB.Where(\"EXISTS (?)\", joinSub).Updates(setMap).Error\n\t\t}\n\t}\n\treturn errors.New(\"unsupported relationship\")\n}\n","sourceCodeStart":893,"sourceCodeEnd":913,"githubUrl":"https://github.com/go-gorm/gorm/blob/1d6ce99528060be18a42be09aca8d39efcb47f28/generics.go#L893-L913","documentation":"This error is the fallback return of setCreateOrUpdateG.handleAssociation in generics.go. That function implements association-level Unlink/Delete/Update operations by dispatching on the relationship type (HasOne, HasMany, BelongsTo, Many2Many) and the operation type (clause.OpUnlink, OpDelete, OpUpdate). If the relationship/op combination is not one of the handled cases, execution falls through the switch and returns errors.New(\"unsupported relationship\"). It means GORM cannot translate the association operation you requested into SQL for this relation shape.","triggerScenarios":"Using the generics-based association mutation API (e.g. Association(column) driven ops) with an operation type other than Unlink/Delete/Update, or a relationship whose References are incomplete (nil PrimaryKey refs, e.g. broken composite/foreignKey tags) so it does not match any case; also any relation type that is not has-one/has-many/belongs-to/many-to-many.","commonSituations":"Custom association-op clauses built with clause.Association{Type: ...} values GORM does not handle; models where foreignKey/references tags are misdeclared so the parsed relationship has no usable references; code that worked against one GORM version but passes a new op type after upgrading; calling the internal generics path directly instead of the public Association API.","solutions":["Use the public Association API operations that are implemented: Replace/Append/Delete/Clear (which map to Unlink/Delete/Update ops).","Check the relation's gorm tags (foreignKey, references, joinForeignKey, joinReferences) and fix them so schema.Parse builds complete References.","Print rel.Type and op.Type in a debug session to see which case is being skipped, then restructure the call to use a supported combination.","For unsupported shapes (e.g. polymorphic join variants), perform the join-table or FK updates manually with db.Exec/db.Updates."],"exampleFix":"// before: custom op falls through the switch\ndb.Model(&user).Association(\"Pets\").Unscoped().Delete(&pet) // hits unsupported path via custom clause\n\n// after: use the supported Delete op\ndb.Model(&user).Association(\"Pets\").Delete(&pet)","handlingStrategy":"validation","validationCode":"// before calling association ops, confirm the relation type is supported\nassoc := tx.Model(&user).Association(\"Pets\")\nif assoc.Error != nil { return assoc.Error }\nswitch assoc.Relationship.Type {\ncase schema.HasOne, schema.HasMany, schema.BelongsTo, schema.Many2Many:\n    // supported by handleAssociation\ndefault:\n    return fmt.Errorf(\"relation %s of type %v unsupported\", \"Pets\", assoc.Relationship.Type)\n}","typeGuard":null,"tryCatchPattern":"if err := tx.Model(&user).Association(\"Pets\").Delete(&pet); err != nil {\n    if strings.Contains(err.Error(), \"unsupported relationship\") {\n        // fall back to manual join-table / FK updates\n    }\n}","preventionTips":["Prefer the public Association API (Replace/Append/Delete/Clear) over hand-built clause.Association ops.","Validate foreignKey/references tags with a startup schema smoke test for every relation you mutate.","Watch GORM release notes when upgrading - the generics association path is evolving."],"tags":["gorm","associations","schema","api-misuse"],"backgroundTag":null,"analyzedSha":"1d6ce99528060be18a42be09aca8d39efcb47f28","analyzedAt":"2026-08-15T13:01:23.433Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}