Environment variable missing in preview but not local? Check build-time versus runtime scope

When an environment variable works locally but fails in preview, check whether the app needs it at build time, runtime, or both.

This bug often appears after a deploy where the code did not change much. Local development reads a `.env` file, but preview runs through a hosting platform, CI pipeline, serverless function, worker, or container. A value can be available to the build command but absent when the server handles a request. The reverse can also happen: runtime has the value, but static generation or bundling needed it earlier.

Start by naming the variable and its purpose. Then identify who reads it: frontend bundle, server route, worker, job queue, webhook handler, or test runner. Public client variables often need a different prefix from server-only secrets. A missing prefix can make a value invisible to the browser bundle even though it exists in the hosting settings.

Next, compare scopes. Is the value attached to production only, but not preview? Is it attached to the wrong project? Was it added after the last deploy without redeploying? Does the platform require separate settings for build, runtime, and scheduled jobs? Each answer points to a different fix.

Avoid printing the secret. Instead, add a redacted startup check or a health endpoint that reports whether the required config is present. The useful evidence is visibility, not the value itself.

Environment variable missing in preview but not local? Check build-time versus runtime scope

// COMMENTS

ON THIS PAGE