Vercel "Environment Variable references Secret which does not exist" in CI

Your vercel.json (or project config) declares an environment variable whose value points at a named secret with the @secret-name syntax, but no secret by that name exists in the project. The deploy is rejected before building.

What this error means

A deploy fails with "Error: Environment Variable \"DATABASE_URL\" references Secret \"database-url\", which does not exist."

Error: Environment Variable "DATABASE_URL" references Secret "database-url", which does not exist.

Common causes

A secret reference with no matching secret

The legacy @secret-name reference in vercel.json env points at a secret that was never created or was deleted.

The env var lives in a different environment

The secret exists for Preview but the deploy targets Production (or the reverse), so the referenced value is absent for this deploy.

How to fix it

Define the environment variable directly

1. Add the variable in Vercel project settings for the target environment.
2. Remove the legacy @secret-name reference from vercel.json if you set the value in settings.
3. Redeploy so the value resolves.

# define for all environments
vercel env add DATABASE_URL production

Create the referenced secret

If you keep the @secret-name reference, create the matching secret so the lookup succeeds.

vercel secrets add database-url "postgres://..."

How to prevent it

• Set environment variables in project settings per environment.
• Avoid dangling @secret-name references in vercel.json.
• Confirm the target environment has the variable before deploying.

Related guides