Prisma include na přejmenovanou relaci — typ „never", build projde, runtime 500
import { Aside } from ‘@astrojs/starlight/components’;
Symptom
Sekce “Symptom”Jedna konkrétní obrazovka přestane fungovat, zbytek aplikace jede:
- endpoint detailu vrací HTTP 500
- modal / detailová stránka se neotevře nebo zůstane v načítání
- v logu opakovaně
Unknown field \payment` for include statement on model `BankTransaction`. Available options are marked with ?.` tsc --noEmiti produkční build projdou bez jediné chyby- CI je zelené, deploy proběhne, problém se ukáže až u uživatelů
Zákeřné na tom je, že chyba nevznikne v okamžiku přejmenování, ale až když se poprvé vygeneruje nový Prisma klient — mezi commitem a projevem tak může být i několik nasazení.
Root cause
Sekce “Root cause”Ve schématu se relace změnila z 1:1 na 1:N a s ní i její název:
model BankTransaction { // dřív: // payment Payment? // nově: payments Payment[]}Volající kód ale zůstal na starém názvu:
const DETAIL_INCLUDE = { bankAccount: { select: { id: true, name: true } }, payment: { // ← relace už se jmenuje payments include: { invoice: { select: { id: true, number: true } } }, },} as const;
const tx = await prisma.bankTransaction.findUnique({ where: { id }, include: DETAIL_INCLUDE,});Proč to typecheck nechytí: Prisma neoznačí neznámý klíč v include jako chybu — odvodí pro něj typ never. Výsledek se pak tváří jako { ..., payment: never }, což je přiřaditelné kamkoli a nikde to nezaskřípe. as const situaci ještě zhorší: objekt se předává jako hodnota, takže se neporovnává proti XxxInclude v místě zápisu. Kontrola typu tedy potvrdí kód, který databáze odmítne.
Validace probíhá až za běhu v query engine — proto 500 místo červeného buildu.
Fix
Sekce “Fix”Srovnat include se schématem a výsledek převést do tvaru, který očekává API kontrakt a frontend:
const DETAIL_INCLUDE = { bankAccount: { select: { id: true, name: true } }, payments: { // ← skutečný název relace include: { invoice: { select: { id: true, number: true } } }, },} as const;
/** * DB vrací seznam, API kontrakt drží JEDNU účinnou položku. * Signatura vyžaduje `payments` — další přejmenování shodí build, ne produkci. */function toDetailShape<P, T extends { payments: P[] }>( row: T): Omit<T, "payments"> & { payment: P | null } { const { payments, ...rest } = row; return { ...rest, payment: payments[0] ?? null };}
const row = await prisma.bankTransaction.findUnique({ where: { id }, include: DETAIL_INCLUDE });if (!row) return notFound();const tx = toDetailShape(row); // frontend dál čte tx.paymentTen helper je tu to podstatné: přesune chybu z runtime do buildu. S ním tsc na starém názvu spadne (Argument of type '{ ...; payment: never; }' is not assignable to parameter of type '{ payments: unknown[]; }').
Jak to najít u sebe
Sekce “Jak to najít u sebe”Přejmenování relace se typicky projeví jen na některých místech, takže hledej systematicky:
# 1) vypiš relace modelu ze schématuawk '/^model BankTransaction/,/^}/' prisma/schema.prisma
# 2) najdi v kódu starý název v include/select (pozor na false positives typu paymentId)grep -rn 'payment:' src/ | grep -vE 'payments:|paymentId|paymentMethod|paymentTerms'
# 3) posbírej runtime důkazy z logu — tohle je jediné místo, kde se to projevígrep -c 'Unknown field .* for include statement' /path/to/app-error.logBod 3 je zároveň dobrý smoke test po každé migraci schématu: pokud počet po nasazení roste, něco jsi minul.
Poučení
Sekce “Poučení”- Zelený build není důkaz, že dotazy sedí se schématem. U Prisma platí, že typová kontrola pokrývá tvar výsledku, ne existenci polí v
include. - Přejmenování relace je breaking change pro celý repozitář, ne lokální úprava schématu. Patří k němu grep a proklikání dotčených obrazovek.
- Když část kódu na migraci zareaguje a část ne, vzniká nejhorší varianta: většina appky funguje a rozbitá je jedna obrazovka, které si nikdo nevšimne dny.
- Pomáhá držet stabilní API kontrakt (ven jde
payment) nezávisle na tvaru v DB (payments) — frontend pak migraci schématu vůbec nepocítí.