Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Prisma CLI fails with PrismaConfigEnvError about DATABASE_URL

ErrorPrismaConfigEnvError: Missing required environment variable: DATABASE_URL

Short answer

Prisma 7 does not read .env files by itself. prisma.config.ts is loaded by every CLI command, and env('DATABASE_URL') throws when the variable is not in process.env at that moment. Load the .env file at the top of the config, or pass the variable on the command line, or stop using env() for commands that need no database.

  • Applies to Prisma 7, Next.js 15, Next.js 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the variable is visible to a plain Node.js process started from the project folder. Prisma CLI sees the same environment, not what Next.js loads.

    node -e "console.log(process.env.DATABASE_URL ? 'set' : 'missing')"
  2. 2Match what you see, then jump to its fix

    1. 1DATABASE_URL is in .env, yet npx prisma migrate dev or prisma generate fails at onceThe .env file is never loaded by prisma.config.tsFix
    2. 2The error appears in CI during prisma generate, where no database is configured on purposeA command that needs no database still runs env()Fix
    3. 3The error appears on migrate deploy in a pipeline or on a serverA command that connects is run without the variableFix

What does the error look like?

  • PrismaConfigEnvError: Missing required environment variable: DATABASE_URL
  • PrismaConfigEnvError: Cannot resolve environment variable: DATABASE_URL

Cause 1 of 3

The .env file is never loaded by prisma.config.ts

1Check

Open prisma.config.ts and look for an import that loads the file. Prisma 7 no longer loads .env on its own, and Next.js only loads it inside its own runtime, not for the Prisma CLI.

head -n 5 prisma.config.ts

2Fix

Add the dotenv import as the first line of prisma.config.ts, so the variables exist before env() runs. In a Next.js project that keeps secrets in .env.local, use @next/env instead, which follows the same file order as Next.js.

// prisma.config.ts
import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: { url: env("DATABASE_URL") },
});

// Next.js alternative, with .env.local support:
// import { loadEnvConfig } from "@next/env";
// loadEnvConfig(process.cwd());

3Verify

Run a command that reads the config.

npx prisma validate

Confirmed by prisma.io

Did this fix it?

Cause 2 of 3

A command that needs no database still runs env()

1Check

Every CLI command loads the config file, so env() throws even for prisma generate, which never connects. Check whether your CI job really sets the variable.

grep -n "env(" prisma.config.ts

2Fix

Read the variable with process.env instead of env(), with an empty-string fallback, so generate works without a database. Keep the real value for migrate and deploy steps.

// prisma.config.ts
export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: { url: process.env.DATABASE_URL ?? "" },
});

3Verify

Run generate with the variable unset.

env -u DATABASE_URL npx prisma generate

Confirmed by prisma.io

Did this fix it?

Cause 3 of 3

A command that connects is run without the variable

1Check

A deploy shell does not read your local .env. Confirm the variable is exported in that shell.

printenv DATABASE_URL | cut -c1-12

2Fix

Set the variable on the command itself, or export it in the pipeline settings.

DATABASE_URL="postgresql://user:pass@host:5432/db" npx prisma migrate deploy

3Verify

The command now connects instead of failing at config load.

DATABASE_URL="postgresql://user:pass@host:5432/db" npx prisma migrate status

Confirmed by prisma.io

Did this fix it?

How do I stop it coming back?

  • Keep the dotenv or @next/env line as the first statement of prisma.config.ts.
  • Set DATABASE_URL in the CI job for steps that connect, and leave it out of steps that only generate.
  • Do not copy a real connection string into docs or chat when asking for help; use a placeholder.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.