{"record":{"id":"723c636b4da3529a","repo":"go-gorm/gorm","slug":"invalid-polymorphic-foreign-keys-v-for-v-on-fie","errorCode":null,"errorMessage":"invalid polymorphic foreign keys %+v for %v on field %s","messagePattern":"invalid polymorphic foreign keys %\\+v for (.+?) on field (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"schema/relationship.go","lineNumber":241,"sourceCode":"\t\tschema.err = fmt.Errorf(\"invalid polymorphic type %v for %v on field %s, missing field %s\",\n\t\t\trelation.FieldSchema, schema, field.Name, polymorphic+\"Type\")\n\t}\n\n\tif relation.Polymorphic.PolymorphicID == nil {\n\t\tschema.err = fmt.Errorf(\"invalid polymorphic type %v for %v on field %s, missing field %s\",\n\t\t\trelation.FieldSchema, schema, field.Name, polymorphic+\"ID\")\n\t}\n\n\tif schema.err == nil {\n\t\trelation.References = append(relation.References, &Reference{\n\t\t\tPrimaryValue: relation.Polymorphic.Value,\n\t\t\tForeignKey:   relation.Polymorphic.PolymorphicType,\n\t\t})\n\n\t\tprimaryKeyField := schema.PrioritizedPrimaryField\n\t\tif len(relation.foreignKeys) > 0 {\n\t\t\tif primaryKeyField = schema.LookUpField(relation.foreignKeys[0]); primaryKeyField == nil || len(relation.foreignKeys) > 1 {\n\t\t\t\tschema.err = fmt.Errorf(\"invalid polymorphic foreign keys %+v for %v on field %s\", relation.foreignKeys,\n\t\t\t\t\tschema, field.Name)\n\t\t\t}\n\t\t}\n\n\t\tif primaryKeyField == nil {\n\t\t\tschema.err = fmt.Errorf(\"invalid polymorphic type %v for %v on field %s, missing primaryKey field\",\n\t\t\t\trelation.FieldSchema, schema, field.Name)\n\t\t\treturn\n\t\t}\n\n\t\t// use same data type for foreign keys\n\t\tif copyableDataType(primaryKeyField.DataType) {\n\t\t\trelation.Polymorphic.PolymorphicID.DataType = primaryKeyField.DataType\n\t\t}\n\t\trelation.Polymorphic.PolymorphicID.GORMDataType = primaryKeyField.GORMDataType\n\t\tif relation.Polymorphic.PolymorphicID.Size == 0 {\n\t\t\trelation.Polymorphic.PolymorphicID.Size = primaryKeyField.Size\n\t\t}","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/go-gorm/gorm/blob/1d6ce99528060be18a42be09aca8d39efcb47f28/schema/relationship.go#L223-L259","documentation":"In a polymorphic relation with an explicit `foreignKeys` tag (e.g. `gorm:\"polymorphic:Owner;foreignKey:CustomKey\"`), GORM resolves exactly one primary key field on the owner schema via schema.LookUpField. The error fires when the named key does not exist on the owner schema or when more than one foreign key is listed (polymorphic relations support only one).","triggerScenarios":"`gorm:\"polymorphic:Owner;foreignKey:NoSuchField\"` on a relation, or `foreignKey:A,B` (comma-separated) which makes len(relation.foreignKeys) > 1.","commonSituations":"Copy-pasting a composite foreign key list from a belongs-to relation into a polymorphic one; renaming the owner's key field without updating the tag; embedding the key in a nested struct not reachable by LookUpField.","solutions":["Use a single existing field name in foreignKeys, e.g. `foreignKey:ID`.","Remove the foreignKeys clause entirely to let GORM use PrioritizedPrimaryField.","If a composite key is truly needed, polymorphic relations do not support it — model it as a plain belongs-to with an explicit type column."],"exampleFix":"// before\nChildren []Cat `gorm:\"polymorphic:Owner;foreignKey:Key1,Key2\"`\n\n// after\nChildren []Cat `gorm:\"polymorphic:Owner\"` // single implicit primary key","handlingStrategy":"validation","validationCode":"// Polymorphic foreignKeys must be exactly one existing owner field\ntype User struct {\n    ID uint `gorm:\"primaryKey\"`\n}\n// tag must be: polymorphic:Owner;foreignKey:ID  (single, existing)","typeGuard":null,"tryCatchPattern":"if err := db.AutoMigrate(&User{}); err != nil {\n    if strings.Contains(err.Error(), \"invalid polymorphic foreign keys\") {\n        return fmt.Errorf(\"use exactly one existing field in foreignKeys for polymorphic relations: %w\", err)\n    }\n    return err\n}","preventionTips":["Never list multiple foreign keys on a polymorphic relation.","Omit foreignKeys on polymorphic relations unless overriding the primary key is required.","Add a CI grep for 'foreignKey:.*,.*polymorphic' patterns in tags."],"tags":["gorm","polymorphic","foreign-key","relation"],"backgroundTag":null,"analyzedSha":"1d6ce99528060be18a42be09aca8d39efcb47f28","analyzedAt":"2026-08-15T13:01:23.433Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}