Latest Results
fix(client): improve adapter-related Prisma 7 error messages (#29624)
Both the runtime and TypeScript errors that users get when they forget
to pass a driver adapter to the `PrismaClient` constructor were
confusing and not actionable. This PR makes both helpful and points them
at the docs.
Fixes
[TML-2681](https://linear.app/prisma-company/issue/TML-2681/improve-adapter-related-prisma-7-error-messages).
## Runtime improvements
- **Validation error**
(`packages/client/src/runtime/utils/validatePrismaClientOptions.ts`) —
replaces `Using engine type "client" requires either "adapter" or
"accelerateUrl" to be provided to PrismaClient constructor.` with a
clearer message that includes a copy-pasteable example using
`@prisma/adapter-pg` and a link to <https://pris.ly/d/driver-adapters>.
Accelerate is mentioned only as a brief footnote so adapter is the
obvious primary path.
- **Defense-in-depth error in `ClientEngine`** — drops the "engine type
`client`" wording and reuses the same single-line message + docs link.
- **`new PrismaClient()` with no arguments** (`getPrismaClient.ts`) —
replaces the multi-paragraph `PrismaClient needs to be constructed with
a non-empty, valid PrismaClientOptions` boilerplate with the same
concrete example, so all three runtime errors agree on wording and call
to action.
- **Inline snapshot** in `validatePrismaClientOptions.test.ts` updated.
## TypeScript improvements
- **Restructured `PrismaClientOptions`** from `(WithAdapter |
WithAccelerateUrl) & Base` into a discriminated union of named
interfaces:
- `PrismaClientBaseOptions`
- `PrismaClientOptionsWithAdapter`
- `PrismaClientOptionsWithAccelerateUrl`
- `PrismaClientOptions = PrismaClientOptionsWithAccelerateUrl |
PrismaClientOptionsWithAdapter`
Mirrored in the TS generator (`PrismaNamespaceFile.ts`). The new TS
generator now emits four exported types; the legacy JS generator keeps
its single flat `PrismaClientOptions` interface for backwards
compatibility but gets the new JSDoc treatment.
- **Rich JSDoc** on the `adapter` and `accelerateUrl` properties — full
example with `PrismaPg`, a `**required**` callout, and a link to
<https://pris.ly/d/driver-adapters>. TypeScript surfaces these in
autocomplete (it doesn't on hover after the property is written — that's
[microsoft/TypeScript#32542](https://github.com/microsoft/TypeScript/issues/32542),
and the same limitation affects query args like
`where`/`select`/`take`).
- **`Prisma.PrismaClientConstructorArgs<Options>` helper** as the
constructor parameter type. It resolves to plain `PrismaClientOptions`
when `Options` defaults to itself (i.e. `new PrismaClient()` or `new
PrismaClient({})`), and falls back to `Subset<…>` otherwise. So instead
of the noisy `Subset<PrismaClientOptions, PrismaClientOptions>`, the
error now reads `not assignable to parameter of type
'PrismaClientOptions'`, while still rejecting unknown properties for
object-literal arguments.
## Union order matters
The `PrismaClientOptions` union lists the Accelerate branch first and
the adapter branch second, both in the runtime types and in the
generator output. TypeScript's missing-property error elaboration for a
discriminated union reports against the second union member, so this
makes `new PrismaClient({ log: [...] })` say `Property 'adapter' is
missing in type ... but required in type
'PrismaClientOptionsWithAdapter'` (the recommended option for most
users) instead of suggesting `accelerateUrl`.
`AGENTS.md` documents this and the other constraints so future changes
don't accidentally regress them.
## Resulting errors
For these three call sites:
```ts
new PrismaClient() // ❶
new PrismaClient({}) // ❷
new PrismaClient({ adapter, accelerateUrl: '…' }) // ❸
```
TypeScript now says:
```
❶ Expected 1 arguments, but got 0.
❷ Argument of type '{}' is not assignable to parameter of type 'PrismaClientOptions'.
❸ Argument of type '{ adapter: SqlDriverAdapterFactory; accelerateUrl: string; }' is not assignable to parameter of type 'PrismaClientOptions'.
Types of property 'accelerateUrl' are incompatible.
Type 'string' is not assignable to type 'undefined'.
```
For `new PrismaClient({ log: ['query'] })` (no adapter at all):
```
Argument of type '{ log: "query"[]; }' is not assignable to parameter of type 'PrismaClientOptions'.
Property 'adapter' is missing in type '{ log: "query"[]; }' but required in type 'PrismaClientOptionsWithAdapter'.
```
And the runtime validation, if the type system is bypassed:
```
PrismaClientConstructorValidationError: PrismaClient requires a driver adapter to connect to your database, but none was provided.
Pass a driver adapter to the PrismaClient constructor, for example:
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client'
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })
Learn more about driver adapters: https://pris.ly/d/driver-adapters
If you use Prisma Accelerate instead of connecting to your database directly, pass `accelerateUrl` to the PrismaClient constructor instead of `adapter`.
Read more at https://pris.ly/d/client-constructor
```
## Validation
- `pnpm --filter @prisma/client exec jest src/__tests__` — 340 passed
(including the `types.test.ts` tsd checks).
- `pnpm --filter @prisma/client-generator-ts test` — 39 passed.
- `pnpm --filter @prisma/client-generator-js test` — 17 passed.
- Full `pnpm build` from the root completes (44/44 turborepo tasks).
- Sandbox regenerated and the error messages above verified against the
real generated client with both `tsc` 5.4 and `tsgo`.
Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net> fix(client): improve adapter-related Prisma 7 error messages
Both the runtime and the TypeScript errors that users get when they
forget to pass a driver adapter to the `PrismaClient` constructor were
confusing and not actionable.
Runtime improvements
====================
- Replace the validation error `Using engine type "client" requires
either "adapter" or "accelerateUrl" to be provided to PrismaClient
constructor.` with a copy-pasteable example that uses
`@prisma/adapter-pg` and a link to https://pris.ly/d/driver-adapters.
Accelerate is mentioned only as a brief footnote.
- Replace the `ClientEngine` defense-in-depth error
(`Missing configured driver adapter. Engine type \`client\` requires
an active driver adapter.`) with a single-line variant of the same
message; drop the "engine type 'client'" wording entirely.
- Replace the `PrismaClient was constructed with non-empty…` error from
`getPrismaClient` (raised on `new PrismaClient()` with no arguments)
with the same concrete example so all three runtime errors agree on
wording and call to action.
- Update the inline snapshot in `validatePrismaClientOptions.test.ts`.
Type improvements
=================
- Restructure `PrismaClientOptions` from `(WithAdapter | WithAccelerateUrl) & Base`
into a discriminated union of named interfaces:
`PrismaClientBaseOptions`, `PrismaClientOptionsWithAdapter`,
`PrismaClientOptionsWithAccelerateUrl`, with
`PrismaClientOptions = PrismaClientOptionsWithAccelerateUrl | PrismaClientOptionsWithAdapter`.
Mirror the same shape in the TS generator
(`PrismaNamespaceFile.ts`).
- Rich JSDoc on `adapter`/`accelerateUrl` properties with a working
example and link to the docs. TypeScript surfaces these in autocomplete
(hover doesn't, due to microsoft/TypeScript#32542).
- Add a `Prisma.PrismaClientConstructorArgs<Options>` helper used as the
constructor parameter type. It resolves to plain `PrismaClientOptions`
when `Options` defaults to itself (`new PrismaClient()` or
`new PrismaClient({})`), and falls back to `Subset<…>` otherwise. This
makes the error message read `not assignable to parameter of type
'PrismaClientOptions'` instead of the noisy
`Subset<PrismaClientOptions, PrismaClientOptions>`, while still
rejecting unknown properties for literal arguments.
Union order matters
===================
`PrismaClientOptions` lists the Accelerate branch first and the adapter
branch second, in both the runtime types and the TS generator output.
TypeScript's missing-property error elaboration for a discriminated
union reports against the second union member, so this makes
`new PrismaClient({ log: [...] })` say
`Property 'adapter' is missing in type … but required in type
'PrismaClientOptionsWithAdapter'` (the recommended option for most
users) instead of suggesting `accelerateUrl`.
`AGENTS.md` documents this and the other constraints (declaration
layout, hover-vs-autocomplete JSDoc behavior, etc.) so future changes
don't accidentally regress them.
Fixes TML-2681.
Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net> fix(client): improve adapter-related Prisma 7 error messages
Both the runtime and the TypeScript errors that users get when they
forget to pass a driver adapter to the `PrismaClient` constructor were
confusing and not actionable.
Runtime improvements
====================
- Replace the validation error `Using engine type "client" requires
either "adapter" or "accelerateUrl" to be provided to PrismaClient
constructor.` with a copy-pasteable example that uses
`@prisma/adapter-pg` and a link to https://pris.ly/d/driver-adapters.
Accelerate is mentioned only as a brief footnote.
- Replace the `ClientEngine` defense-in-depth error
(`Missing configured driver adapter. Engine type \`client\` requires
an active driver adapter.`) with a single-line variant of the same
message; drop the "engine type 'client'" wording entirely.
- Replace the `PrismaClient was constructed with non-empty…` error from
`getPrismaClient` (raised on `new PrismaClient()` with no arguments)
with the same concrete example so all three runtime errors agree on
wording and call to action.
- Update the inline snapshot in `validatePrismaClientOptions.test.ts`.
Type improvements
=================
- Restructure `PrismaClientOptions` from `(WithAdapter | WithAccelerateUrl) & Base`
into a discriminated union of named interfaces:
`PrismaClientBaseOptions`, `PrismaClientOptionsWithAdapter`,
`PrismaClientOptionsWithAccelerateUrl`, with
`PrismaClientOptions = PrismaClientOptionsWithAccelerateUrl | PrismaClientOptionsWithAdapter`.
Mirror the same shape in the TS generator
(`PrismaNamespaceFile.ts`).
- Rich JSDoc on `adapter`/`accelerateUrl` properties with a working
example and link to the docs. TypeScript surfaces these in autocomplete
(hover doesn't, due to microsoft/TypeScript#32542).
- Add a `Prisma.PrismaClientConstructorArgs<Options>` helper used as the
constructor parameter type. It resolves to plain `PrismaClientOptions`
when `Options` defaults to itself (`new PrismaClient()` or
`new PrismaClient({})`), and falls back to `Subset<…>` otherwise. This
makes the error message read `not assignable to parameter of type
'PrismaClientOptions'` instead of the noisy
`Subset<PrismaClientOptions, PrismaClientOptions>`, while still
rejecting unknown properties for literal arguments.
Union order matters
===================
`PrismaClientOptions` lists the Accelerate branch first and the adapter
branch second, in both the runtime types and the TS generator output.
TypeScript's missing-property error elaboration for a discriminated
union reports against the second union member, so this makes
`new PrismaClient({ log: [...] })` say
`Property 'adapter' is missing in type … but required in type
'PrismaClientOptionsWithAdapter'` (the recommended option for most
users) instead of suggesting `accelerateUrl`.
`AGENTS.md` documents this and the other constraints (declaration
layout, hover-vs-autocomplete JSDoc behavior, etc.) so future changes
don't accidentally regress them.
Fixes TML-2681.
Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net> fix(client): improve adapter-related Prisma 7 error messages
Both the runtime and the TypeScript errors that users get when they
forget to pass a driver adapter to the `PrismaClient` constructor were
confusing and not actionable.
Runtime improvements
====================
- Replace the validation error `Using engine type "client" requires
either "adapter" or "accelerateUrl" to be provided to PrismaClient
constructor.` with a copy-pasteable example that uses
`@prisma/adapter-pg` and a link to https://pris.ly/d/driver-adapters.
Accelerate is mentioned only as a brief footnote.
- Replace the `ClientEngine` defense-in-depth error
(`Missing configured driver adapter. Engine type \`client\` requires
an active driver adapter.`) with a single-line variant of the same
message; drop the "engine type 'client'" wording entirely.
- Replace the `PrismaClient was constructed with non-empty…` error from
`getPrismaClient` (raised on `new PrismaClient()` with no arguments)
with the same concrete example so all three runtime errors agree on
wording and call to action.
- Update the inline snapshot in `validatePrismaClientOptions.test.ts`.
Type improvements
=================
- Restructure `PrismaClientOptions` from `(WithAdapter | WithAccelerateUrl) & Base`
into a discriminated union of named interfaces:
`PrismaClientBaseOptions`, `PrismaClientOptionsWithAdapter`,
`PrismaClientOptionsWithAccelerateUrl`, with
`PrismaClientOptions = PrismaClientOptionsWithAccelerateUrl | PrismaClientOptionsWithAdapter`.
Mirror the same shape in the TS generator
(`PrismaNamespaceFile.ts`).
- Rich JSDoc on `adapter`/`accelerateUrl` properties with a working
example and link to the docs. TypeScript surfaces these in autocomplete
(hover doesn't, due to microsoft/TypeScript#32542).
- Add a `Prisma.PrismaClientConstructorArgs<Options>` helper used as the
constructor parameter type. It resolves to plain `PrismaClientOptions`
when `Options` defaults to itself (`new PrismaClient()` or
`new PrismaClient({})`), and falls back to `Subset<…>` otherwise. This
makes the error message read `not assignable to parameter of type
'PrismaClientOptions'` instead of the noisy
`Subset<PrismaClientOptions, PrismaClientOptions>`, while still
rejecting unknown properties for literal arguments.
Union order matters
===================
`PrismaClientOptions` lists the Accelerate branch first and the adapter
branch second, in both the runtime types and the TS generator output.
TypeScript's missing-property error elaboration for a discriminated
union reports against the second union member, so this makes
`new PrismaClient({ log: [...] })` say
`Property 'adapter' is missing in type … but required in type
'PrismaClientOptionsWithAdapter'` (the recommended option for most
users) instead of suggesting `accelerateUrl`.
`AGENTS.md` documents this and the other constraints (declaration
layout, hover-vs-autocomplete JSDoc behavior, etc.) so future changes
don't accidentally regress them.
Fixes TML-2681.
Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net> Latest Branches
-95%
AmirSa12:feat/tab-completions 0%
0%
© 2026 CodSpeed Technology