error: the datasource.url property is required in your prisma config file when using prisma migrate deploy.

TL;DR

prisma migrate deploy runs in non-interactive environments where .env files are often absent or ignored, so the datasource url resolves to nothing. Fix it by exporting DATABASEURL as a real environment variable in the deploy job (not just a .env file), and keep `url = env("DATABASEURL")` in the datasource block.

error: the datasource.url property is required in your prisma config file when using prisma migrate deploy.

Use this when

• migrate dev works locally but migrate deploy fails in CI or Docker with this error
• The deploy job relies on a .env file that isnt shipped into the container
• An agent wrote the deploy step without wiring the database URL into the environment

Not for this skill when

• The url is set and the failure is about drift, failed migrations, or the shadow database
• The connection is refused or times out (the url is present but wrong)
• You are running migrate dev locally (thats the local-env variant of this error)

Steps

1. Confirm the schema declares the url via env, not hardcoded:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Expected output: the url line exists. If it is missing entirely, add it; the CLI validates the property before it ever reads the value.

1. Export DATABASE_URL in the deploy environment. In a CI job:

env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}

Expected output: the secret is injected as an environment variable for the job step. migrate deploy prefers real env vars over .env files, which is why local dev works and CI fails.

1. In Docker, pass it at container run time rather than baking it into the image:

docker run --env-file ./deploy.env myapp npx prisma migrate deploy

Expected output: the container sees DATABASE_URL and deploy runs. Baking the URL into the image leaks a credential into the layer history, so dont.

1. Verify the variable is visible to the exact command you run, then deploy:

printenv DATABASE_URL | head -c 20
npx prisma migrate deploy

Expected output: the first command prints the start of the URL (proving visibility), and deploy applies pending migrations instead of the datasource.url error.

Variant phrasings

deploy fails but only in a specific stage

One stage exports the variable and another doesnt. Diff the env blocks across stages; the fix is per-stage, not global.

same error with prisma.config.ts

If you moved config to prisma.config.ts, make sure it also provides the datasource url or env wiring. Mixed config files confuse resolution, so consolidate on one.

Why it happens

migrate dev is a local command that happily reads .env from your project dir. migrate deploy is designed for production pipelines where .env files are typically absent (or intentionally excluded), so the url property resolves to nothing and the CLI reports it as missing rather than wrong. The asymmetry between dev and deploy environments is what makes this error show up only at deploy time.

Edge cases

• Some platforms strip env vars between build and run phases; set it in the run phase.
• A trailing newline in the secret value breaks the URL silently; trim it when injecting.
• Preview deployments need their own database URL; pointing them at production is a data-loss accident waiting to happen.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstko2-KSA-CwN1Ts0sh-JeQ