Do this with AI
Install the launch-sync-environment-variables-from-env-example skill from Contentstack agent skills and connect the Launch Deploy Helper profile in MCP Profile Hub. Then ask your agent:
Compare the keys in ./.env.example with the variables on my Launch staging environment as a dry run. List the missing keys and any values that start or end with a quote or a space, without printing the values.
New to this? Set up your AI workbench first.
Launch env vars undefined or deploy stuck in Deploying
Environment variables cause more failed Launch deployments than anything else, and they fail in confusing ways. A deployment sits in Deploying for a long time and then fails without a useful error. Or the build is green and the site is live, but the app behaves as if half its configuration is missing. Or Next.js stops halfway through generating static pages with Error: Invalid URL.
All three come from the same place: the values Launch hands to your build and runtime are not the values your code expects.
What you'll learn
Which formatting mistakes break Launch environment variable values
The difference between build-time and runtime variables, and where NEXT_PUBLIC_ fits
How to move a local .env file into Launch without bringing its quirks along
How to fail the build early with a clear message when a variable is missing
Symptoms
The deployment status stays on Deploying for many minutes, with no error in the build output, and then flips to failed.
The deployment log ends with Deployment failed: Please try to redeploy the site, or contact support for assistance. and no build error above it.
The build succeeds, but process.env.SOMETHING is undefined or wrong in the running app. The same repository and variables work locally or on another host.
Next.js fails during Generating static pages:
Error: Invalid URL
Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered errors on following paths:
/
/articlesWhy it happens
Launch concept: environment variables belong to one environment. Launch passes them to the build step and to the server-side runtime, exactly as you entered them. Changes only apply to deployments you trigger after saving.
Three things go wrong.
The value is malformed. Locally, a .env file is parsed by a library such as dotenv, which strips surrounding quotes and whitespace. Launch doesn't parse your values that way. If you enter API_KEY="blt123", the quotes are part of the value. A space before or after the value is part of it too. A single unmatched quote, for example in a password, can break the deployment outright, which is when you see the long Deploying state and the generic failure. Private keys are the classic case: they are often stored locally on one line with escaped \n sequences inside quotes, and that form doesn't survive the move.
The variable is missing at build time. Next.js runs your data fetching while it prerenders pages. If that code builds a URL from a variable that isn't set on the Launch environment, new URL(undefined + '/path') throws Invalid URL, and the export fails. It worked locally because your .env.local was there.
NEXT_PUBLIC_ values are frozen into the bundle. Next.js replaces every process.env.NEXT_PUBLIC_* reference in client code with its value during next build. If the variable was missing or wrong at build time, the browser bundle keeps that value until the next build, whatever you change in the settings afterwards.
Fix it
Clean up the values
Open the environment in Launch, go to Settings > Environment Variables, and check every value against these rules:
Wrong | Right |
|---|---|
CONTENTSTACK_API_KEY="blt123" | CONTENTSTACK_API_KEY=blt123 |
SITE_URL= https://example.com | SITE_URL=https://example.com |
DB_PASSWORD=pa'ss | A value without the stray quote, or a new secret |
PRIVATE_KEY='-----BEGIN...\nMIIE...\n-----END...' | The key with real line breaks, no quotes |
For a multi-line value such as a private key, use the form fields (one key, one value) and paste the key with its real line breaks. Don't paste multi-line values into the bulk editor.
Save, then trigger a new deployment. Saving alone changes nothing on the running site.
Paste a .env file the safe way
The bulk editor (Editor Mode) takes one key=value per line, so pasting a .env file is the quickest way to fill an environment. Prepare the file first:
# Print keys and values with quotes and surrounding spaces removed
grep -v '^\s*#' .env.production \
| grep '=' \
| sed -E 's/^[[:space:]]*([A-Za-z_][A-Za-z0-9_]*)[[:space:]]*=[[:space:]]*/\1=/' \
| sed -E 's/[[:space:]]+$//' \
| sed -E "s/=[\"'](.*)[\"']$/=\1/"Check the output by eye before you paste it, and add multi-line values separately in form mode. Don't commit the cleaned file.
If you only need to know which keys are missing, the launch-sync-environment-variables-from-env-example agent skill compares a Launch environment with your .env.example and adds missing keys without touching existing values.
Set build-time variables before the build
Every variable that code running during next build reads must exist on the Launch environment before you deploy. That includes:
everything prefixed with NEXT_PUBLIC_
variables used in generateStaticParams, generateMetadata and statically rendered pages
variables read in next.config.js
Then make the failure readable. Instead of letting new URL() throw deep inside a prerender, check the base URL where you build it:
// lib/env.ts
export function requireEnv(name: string): string {
const value = process.env[name];
if (!value || value.trim() !== value || /^["']|["']$/.test(value)) {
throw new Error(`Environment variable ${name} is missing or has quotes or spaces around it`);
}
return value;
}
export const siteUrl = new URL(requireEnv('NEXT_PUBLIC_SITE_URL'));With this in place, the deployment log names the variable instead of printing Invalid URL.
Redeploy after changing a NEXT_PUBLIC_ value
Because the value lives in the bundle, fixing a NEXT_PUBLIC_ variable always needs a new deployment. If a value has to change without a rebuild, read it on the server at request time and pass it to the client as a prop.
Stay inside the limits
An environment holds up to 128 variables with a total size of 14 KB. If the project uses Cloud Functions, the total must stay under 4 KB, and going over it fails the deployment even for code that deployed fine before. Remove unused variables, or combine related settings into one JSON value and parse it in your code.
Check that it worked
Trigger a new deployment and read its log:
csdx launch:logs --environment production --deployment <deployment-uid> --type dThe build step should pass Generating static pages without errors. For runtime values, request a page that uses them and read the server logs with --type s. If you log configuration at startup, log the variable names and whether they are set, never the values.
Prevent it
Keep a .env.example with every key the app reads, and diff it against each Launch environment before a release.
Run a check before the build so a missing variable fails in seconds instead of halfway through prerendering:
{
"scripts": {
"check-env": "node -e \"for (const k of ['CONTENTSTACK_API_KEY','CONTENTSTACK_DELIVERY_TOKEN','NEXT_PUBLIC_SITE_URL']) if (!process.env[k]) { console.error('Missing ' + k); process.exit(1) }\"",
"build": "npm run check-env && next build"
}
}Enter values without quotes, and add secrets through form mode.
Remember that environments don't share variables. A new environment starts empty unless you fill it.
Key takeaways
Launch uses variable values exactly as entered. Remove quotes and surrounding spaces, and keep real line breaks in private keys.
A long Deploying state followed by a generic failure usually points to a malformed value.
Error: Invalid URL during prerendering means a build-time variable is missing on the Launch environment.
NEXT_PUBLIC_ values are inlined at build time. Change them, then redeploy.
Fail early with a check-env script so the log names the missing variable.
Frequently asked questions
Should I wrap Launch environment variable values in quotes?
No. Enter the bare value. Quotes and stray spaces become part of the value, and unmatched quotes can make the deployment fail.
How do I add a multi-line private key as a Launch environment variable?
Paste it in the form field with its real line breaks and no surrounding quotes. Don't convert the line breaks to escaped \n sequences.
Why does my NEXT_PUBLIC_ variable keep its old value after I changed it?
Next.js inlines NEXT_PUBLIC_ values into the JavaScript bundle during next build. Changing the variable has no effect until you trigger a new deployment.
How many environment variables can a Launch environment have?
Up to 128 per environment, with a total size of 14 KB. When the project uses Cloud Functions, the total must stay under 4 KB.