Vercel "Environment Variable references Secret which does not exist"

Vercel could not resolve an environment variable - either it references a legacy secret (@name) that no longer exists, or the variable simply is not set for the environment being deployed.

What this error means

The deploy fails with references Secret "x", which does not exist, or the build/runtime reads undefined for a variable that works locally. It is deterministic: the variable is missing or mis-referenced for that environment until it is added.

Vercel build log

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

Common causes

Stale @secret reference

A vercel.json or project env entry uses the old @secret-name indirection, but that secret was deleted or never created in this scope.

Variable not set for the target environment

The variable exists for Preview but not Production (or vice versa), or it is a client variable missing its public prefix, so it resolves to undefined where the deploy runs.

How to fix it

Define the variable in Project Settings

Add the variable under Project Settings → Environment Variables for the exact environment (Production/Preview/Development).
For client-exposed values, use the framework’s public prefix (VITE_, NEXT_PUBLIC_).
Remove obsolete @secret references; set plain values or use the current env-var UI.

Verify what the deploy sees

Pull the project env locally to confirm which variables exist per environment.

Terminal

vercel env ls
vercel env pull .env.production   # inspect resolved values

How to prevent it

Configure required env vars per environment in Project Settings.
Prefer plain env vars over the legacy @secret indirection.
Use the correct public prefix for client-exposed variables.