Skip to main content
Contentstack MCP profile hub is in general availability!

Fix failing Launch builds

•
4 min read

Most failed Launch deployments come down to four causes. Environment variables are set differently than on your machine. The Node version isn't the one you think. npm can't log in to a private registry. Or Launch looks for the build output in the wrong place. Each one has a recognizable symptom, often an exact log line, and a fix that takes a few minutes once you know which one you have.

This guide is for anyone deploying a Next.js, React or other Node-based site to Contentstack Launch from Git or a file upload. The examples use Next.js where a framework matters.

What you'll learn

  • How to read a failed deployment and find the line that matters

  • How to match a symptom to the chapter that fixes it

  • What the four chapters cover and when to skip ahead

Start with the deployment log

Launch concept: every deployment has its own deployment log with the install, build and packaging steps. Runtime errors from a live site go to the server logs instead.

Open the failed deployment in the Launch UI, or read the log from a terminal with the Launch CLI plugin:

csdx launch:logs --environment production --deployment <deployment-uid> --type d

Scroll to the first error, not the last one. Deployment failed: Please try to redeploy the site, or contact support for assistance. is the generic closing line Launch prints for almost every failure. The useful line is above it, in the step that failed: installing dependencies, building, or packaging.

If the build succeeded and the site is live but broken, check the server logs (--type s) as well. A variable that is missing at runtime shows up there, not in the deployment log.

Match your symptom to a chapter

What you see

Likely cause

Chapter

Deployment sits in Deploying for a long time, then fails with no clear error

Malformed environment variable value

Env vars undefined or deploy stuck

Build succeeds, but process.env values are undefined or wrong in the app

Spaces or quotes in a value, or a variable missing at build time

Env vars undefined or deploy stuck

Error: Invalid URL while Next.js is generating static pages

A build-time variable is missing

Env vars undefined or deploy stuck

Node.js v18 and below are no longer supported on Launch

The environment still runs Node 18

Node version errors

An old environment fails while a new one from the same repo works

Node version pinned to the old default

Node version errors

npm error code E401 and Incorrect or missing password

No auth token for a private registry

Private npm packages and E401

Warning: Invalid output directory

Output directory or monorepo setup

Output directory, monorepos and 404s

NoSuchKey: The specified key does not exist after a successful deployment

Wrong output directory, or an SPA without a fallback

Output directory, monorepos and 404s

DiagramMermaid

How the chapters fit together

Each chapter follows the same pattern: symptoms with exact error text, why it happens, the fix, how to check it worked, and how to keep it from coming back. Read the one your symptom points to.

  1. Env vars undefined or deploy stuck covers value formatting, build-time versus runtime variables, NEXT_PUBLIC_ inlining and pasting a .env file into Launch.

  2. Node version errors covers the Node 18 retirement, engines.node, and why existing environments don't upgrade on their own.

  3. Private npm packages and E401 covers .npmrc with ${NPM_TOKEN} and keeping tokens out of Git.

  4. Output directory, monorepos and 404s covers Invalid output directory, NoSuchKey, SPA fallbacks, Turborepo and Nx, and package manager support.

If the deployment builds fine but the live site returns a CF error code, a 504 or a 413, that is a runtime problem. Go to Launch error codes decoded. If you want an agent to read the logs and propose the fix, see Debug a failing Launch deploy with an agent. To stop broken builds before they reach production, run them from your pipeline with Deploy from CI with the Launch CLI, REST API and deploy hooks.

Key takeaways

  • Read the deployment log from the failing step upward. The Deployment failed line at the end is generic.

  • Build-time errors are in the deployment log; runtime errors on a live site are in the server logs.

  • "Works locally" usually means your machine supplies something the clean Launch build machine doesn't: a .env file, an npm login or a Node version.

  • Redeploy after every environment variable or settings change. Nothing applies to an existing deployment.

Frequently asked questions

  • Why does my site build locally but fail on Launch?

    The Launch build machine starts clean. It has no local .env file, no cached npm login and possibly a different Node version, so anything your machine provides implicitly has to be configured explicitly.

  • Do I need to redeploy after changing an environment variable?

    Yes. Environment variable changes only apply to deployments you trigger after saving them. Earlier deployments keep the old values.

  • Where do I find the real error when a deployment fails?

    In the deployment logs of the failed deployment, in the Launch UI or with csdx launch:logs --type d. Runtime errors on a live site are in the server logs instead.

  • My deployment sits in Deploying for a long time. Is it hung?

    Usually it is failing slowly. Let it reach the failed state, check the environment variable values, fix them and trigger a new deployment.