Customer documentation
Env vars & logs
Add Vercel environment variables, understand deployment status, and use build logs to diagnose failures.
Environment variables
Enter variables one per line using KEY=value. The portal writes them to the managed Vercel Project so the next deployment can use them during build and runtime.
NEXT_PUBLIC_API_URL=https://api.example.com
CMS_TOKEN=replace-with-secret
FEATURE_FLAG=true- Use public variables only for values that are safe to expose in browser code.
- Do not upload .env files inside ZIPs; add needed values through this field instead.
- One variable goes on each line. Lines without KEY=value format are ignored.
- Changed variables apply to new deployments. Redeploy after adding, removing, or editing variables.
- Quoted values are accepted, but never include passwords or tokens in screenshots or support messages.
Environment variable basics
KEY=value
Each line should have a variable name, equals sign, and value.
Public browser values
Variables prefixed with NEXT_PUBLIC_ or similar framework public prefixes can be exposed to browser code.
Private server values
API tokens, CMS tokens, database URLs, and secret keys should not be public or included in screenshots.
Quotes
Quotes are accepted for many values, but avoid unnecessary quotes unless the app expects them.
Spaces
Do not add extra spaces around the variable name unless the value intentionally includes spaces.
Vercel targets
The portal stores variables for the Vercel production, preview, and development targets for compatibility.
Redeploy
After adding or changing env vars, redeploy so the next Vercel build and runtime can use the new values.
Vercel environments in plain English
Production
The live customer-facing site. Portal deployments target production so the generated URL and connected domains serve the current release.
Preview
Vercel's pre-production environment for testing branch or pull-request changes. The portal stores variables there for compatibility, but the customer flow is production deploys.
Development
Vercel's local-development target used by Vercel tooling. The portal stores variables there for compatibility; local developers still manage their own local setup.
VERCEL_ENV
Vercel exposes the current environment to apps as production, preview, or development. Apps may use it to change behavior.
VERCEL_URL
Vercel exposes the generated deployment host without https://. Apps that need a public origin should still prefer an explicit site URL variable when possible.
Branch-specific variables
The customer portal does not manage branch-specific preview variables. Keep customer production settings in the portal fields.
Environment examples
NEXT_PUBLIC_SITE_URL=https://example.com
NEXT_PUBLIC_API_URL=https://api.example.com
CMS_TOKEN=your-private-token
DATABASE_URL=postgres://user:pass@host/db
FEATURE_FLAG=trueKeep secrets out of tickets
When asking support for help, share the variable name and the error. Do not share the secret value unless support gives you a secure process for doing so.
Site detail page
Live URL
The generated Vercel public URL for the current deployment. Open it to test the live site before adding a custom domain.
Source
Shows whether the site came from GitHub or ZIP upload. GitHub sites also show the repository URL.
Status badge
Shows the current deployment state such as Queued, Building, Ready, Error, Canceled, Deleted, or Unknown.
Build logs
Log output from Vercel's install and build process. Use this first when a deployment fails before going live.
Custom domains
Attach, verify, and remove custom domains for the deployed site.
Actions
Site actions can remove the deployment project when you need to take the site offline.
Build logs vs runtime logs
Build logs
Created while Vercel installs dependencies and builds the deployment. These logs explain install failures, compile errors, missing env vars, and output-directory problems.
Runtime logs
Created after the site is live when serverless functions, API routes, middleware, or server rendering handle requests. These are different from build logs.
Static sites
Plain static HTML/CSS/JS sites may have useful build logs but little or no runtime logging because there are no server functions running per request.
Customer portal
The portal focuses on deployment status and build logs. If a live app throws request-time 500 errors, support may need the route, timestamp, generated URL, and steps to reproduce.
console.log
Logs printed during build appear in build logs. Logs printed inside Vercel Functions or server-side request handlers are runtime logs.
Sensitive values
Never intentionally print API keys, tokens, passwords, or DATABASE_URL values. Treat logs as support evidence, not a place to expose secrets.
How to read build logs
Build logs usually fail near the first real error, not the last line. Read upward from the failure and look for missing packages, missing variables, wrong commands, or wrong output paths.
Command not found
The build command calls a tool that is not installed or the package script is wrong.
Module not found
A dependency is missing, not committed, misspelled, or imported with the wrong path/case.
Environment variable missing
The app expects a variable that was not added in the portal.
Permission denied
A script may not be executable or the command is not valid in the build environment.
Out of memory or timeout
The project may be too large or the build process too heavy. Remove unnecessary files and simplify the build.
No output directory
The build completed but the configured output folder does not exist.
Works locally only
Local .env files, uncommitted files, or machine-specific paths are usually the reason a project works on a laptop but fails in Vercel.
Vercel deployment statuses
QUEUED
The Vercel deployment was created and is waiting to start.
BUILDING
Vercel is installing dependencies, running the build, validating output, or preparing the deployment.
READY
The deployment is live at the generated URL and any connected verified domains.
ERROR
The deployment failed. Open the site detail page and read the logs.
CANCELED
The deployment stopped before completion.
DELETED
The managed project or deployment was removed.
UNKNOWN
Vercel did not return a clear state to the portal. Refresh status or open support if it persists.
What to send support
- Site name and generated live URL if one exists.
- Source type: GitHub or ZIP.
- Framework preset, root directory, build command, output directory, and Node version.
- The first relevant build error lines, not the entire log dump.
- Names of missing environment variables, without secret values.
- What changed since the last successful deployment.
Build logs and failure diagnosis
The build log panel updates while the deployment is running. If the site fails, the logs are the most useful customer-visible evidence.
Install errors
Check package manager lockfiles, dependency versions, registry access, and Node version.
Build script missing
Confirm package.json has the command you entered, usually build.
Wrong root directory
If the app lives in a subfolder, set Root directory to that folder.
Missing env var
Add required KEY=value lines in Environment variables and redeploy.
Output not found
Confirm Output directory matches the folder produced by the build.
Private files missing
ZIP uploads ignore private .env files and GitHub public repos cannot read your local-only files.