{
  "id": "ai-generates-invalid-prisma-relations",
  "type": "failures",
  "category": "failures",
  "locale": "en",
  "url": "/failures/ai-generates-invalid-prisma-relations",
  "title": "How to Fix AI Generating Invalid Prisma Relations",
  "description": "AI agents generate Prisma schema relations with missing back-relations, wrong referential actions, or mismatched field types that fail prisma validate and prisma migrate.",
  "tools": [
    "Cursor",
    "Claude Code",
    "Codex",
    "Windsurf"
  ],
  "stack": [
    "PostgreSQL",
    "TypeScript"
  ],
  "tags": [
    "prisma",
    "postgres",
    "sql"
  ],
  "difficulty": null,
  "updated": "2026-06-08",
  "markdown": "The agent writes a Prisma schema with relations that look correct but fail\n`prisma validate` due to missing back-references, type mismatches, or\nambiguous multi-relation setups.\n\n## The symptom\n\nA relation is declared on one model without its required counterpart on the\nother, or the foreign key field type doesn't match the referenced field.\n\n```prisma\n// schema.prisma — WRONG\nmodel User {\n  id    String @id @default(cuid())\n  posts Post[]\n}\n\nmodel Post {\n  id       String @id @default(cuid())\n  authorId Int    // Int, but User.id is String — type mismatch\n  // Missing: author User @relation(fields: [authorId], references: [id])\n}\n```\n\nRunning `prisma validate` produces:\n\n```\nError: The relation field `posts` on model `User` is missing an opposite\nrelation field on the model `Post`.\n```\n\n## Why it happens\n\nThe agent often writes one side of a relation and forgets to add the other,\nespecially in many-to-many or self-referential cases. It also copies field types\nfrom memory without checking that `authorId` must match the referenced `id`\ntype exactly.\n\n## How to spot it\n\n- `prisma validate` or `prisma migrate dev` fails with a relation error.\n- A model has an array field (one-to-many) but the referenced model has no\n  scalar foreign key or `@relation` attribute.\n- Many-to-many uses explicit join tables with mismatched types.\n- Self-referential models (e.g. category trees) have only one side of the\n  `@relation(name: \"...\")` pair.\n\n## How to fix it\n\nEvery relation must have both sides declared. Foreign key scalar types must\nmatch the referenced field type exactly.\n\n```prisma\n// schema.prisma — CORRECT\nmodel User {\n  id    String @id @default(cuid())\n  posts Post[] // one-to-many: back-reference\n}\n\nmodel Post {\n  id       String @id @default(cuid())\n  authorId String                       // String, matches User.id\n  author   User   @relation(fields: [authorId], references: [id], onDelete: Cascade)\n}\n```\n\nFor a self-referential tree:\n\n```prisma\nmodel Category {\n  id       String     @id @default(cuid())\n  parentId String?\n  parent   Category?  @relation(\"CategoryTree\", fields: [parentId], references: [id])\n  children Category[] @relation(\"CategoryTree\")\n}\n```\n\n```txt\n[ ] Run \"prisma validate\" before \"prisma migrate dev\" — fix all errors first\n[ ] Every @relation on model A has a matching field on model B\n[ ] Foreign key scalar type matches the referenced @id type (String/Int/cuid)\n[ ] Self-referential relations use a named @relation(\"name\") on both sides\n[ ] Explicit many-to-many join tables declare both foreign keys with onDelete\n[ ] onDelete referential action is explicit (Cascade, Restrict, SetNull) — not left to default\n```\n\n## Fix Prompt\n\n```txt title=\"Fix Prompt\"\nThis Prisma schema fails prisma validate. Fix every relation error: add the\nmissing back-reference fields, ensure all foreign key scalar types exactly match\nthe referenced @id type, give every self-referential relation a unique name on\nboth sides, and set explicit onDelete actions (Cascade for required relations,\nSetNull for optional). Run prisma validate after each change until it passes.\n```\n\n## Test\n\n```bash\n# Validate schema before attempting migration\nnpx prisma validate && echo \"Schema OK\" || echo \"FAIL: schema invalid\"\n\n# Also check for type mismatches (Int fk -> String id is a common error)\ngrep -A3 \"@relation\" prisma/schema.prisma\n```"
}