---
title: "Fix failing Launch builds"
url: "https://developers.contentstack.com/guides/fix-failing-launch-builds"
type: "guide"
level: "intermediate"
intent: "fix"
outcome: "You can match a failing Launch deployment to its cause from the log line or symptom and apply the fix that belongs to it."
prerequisites:
  - "A Launch project with at least one environment"
  - "Access to the environment's deployment logs and settings"
  - "The repository the environment builds from"
tags:
  - "headless"
  - "cli"
  - "next"
authors:
  - "Tim Benniks"
published: "2026-12-03T09:00:00.000Z"
updated: "2026-11-15T10:55:58.350Z"
---

# Fix failing Launch builds

- **Authors:** Tim Benniks
- **Published:** 2026-12-03T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:58.350Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** headless, cli, next
- **Chapters:** 4
- **Source:** [https://developers.contentstack.com/guides/fix-failing-launch-builds](https://developers.contentstack.com/guides/fix-failing-launch-builds)

---

## Table of Contents

1. [Launch env vars undefined or deploy stuck in Deploying](#launch-env-vars-undefined-or-deploy-stuck-in-deploying)
2. [Node.js v18 is no longer supported on Launch: fix Node version errors](#nodejs-v18-is-no-longer-supported-on-launch-fix-node-version-errors)
3. [npm error code E401 on Launch: install private packages](#npm-error-code-e401-on-launch-install-private-packages)
4. [Invalid output directory and NoSuchKey 404s on Launch](#invalid-output-directory-and-nosuchkey-404s-on-launch)

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:

```bash
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](/guides/fix-failing-launch-builds/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](/guides/fix-failing-launch-builds/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](/guides/fix-failing-launch-builds/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](/guides/fix-failing-launch-builds/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](/guides/fix-failing-launch-builds/node-version-errors)

npm error code E401 and Incorrect or missing password

No auth token for a private registry

[Private npm packages and E401](/guides/fix-failing-launch-builds/private-npm-packages-and-e401)

Warning: Invalid output directory

Output directory or monorepo setup

[Output directory, monorepos and 404s](/guides/fix-failing-launch-builds/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](/guides/fix-failing-launch-builds/output-directory-monorepos-and-404s)

flowchart TD  A[Deployment failed or site broken] --> B{Which step?}  B -->|Installing dependencies| C{E401 in log?}  C -->|Yes| D[Chapter 3: private npm]  C -->|No| E{Node version error?}  E -->|Yes| F[Chapter 2: Node version]  B -->|Building| G{Invalid URL or undefined env?}  G -->|Yes| H[Chapter 1: env vars]  B -->|Packaging or live site 404| I[Chapter 4: output directory]  B -->|Stuck in Deploying| H## 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.

- [Env vars undefined or deploy stuck](/guides/fix-failing-launch-builds/env-vars-undefined-or-deploy-stuck) covers value formatting, build-time versus runtime variables, NEXT_PUBLIC_ inlining and pasting a .env file into Launch.


- [Node version errors](/guides/fix-failing-launch-builds/node-version-errors) covers the Node 18 retirement, engines.node, and why existing environments don't upgrade on their own.


- [Private npm packages and E401](/guides/fix-failing-launch-builds/private-npm-packages-and-e401) covers .npmrc with ${NPM_TOKEN} and keeping tokens out of Git.


- [Output directory, monorepos and 404s](/guides/fix-failing-launch-builds/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](/guides/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](/guides/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](/guides/deploy-from-ci-with-the-launch-cli-and-api).

## 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.





---

## 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:



```text
Error: Invalid URL
Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered errors on following paths:
  /
  /articles
```

## Why 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:

```bash
# 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:

```ts
// 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:

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

The 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:



```json
{
  "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.





---

## Node.js v18 is no longer supported on Launch: fix Node version errors

You redeploy a site that has been running on Launch for a year, and the build stops before it starts. Nothing in your code changed. A new environment created from the same repository deploys fine. The difference is the Node.js version, and the fix is one field in package.json.

## What you'll learn

- Why older Launch environments fail with a Node 18 error


- Why existing environments don't move to a newer Node version on their own


- How to pin the version with engines.node


- How to confirm which Node version a deployment used



## Symptoms

- The deployment fails right away with:



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

- An environment that deployed fine before fails on redeploy, while a new environment or project from the same repository works.


- You updated your dependencies with npm update or pnpm update and the error is still there.


- After a platform update, a feature that depends on the runtime behaves differently, and you want to go back to the previous major version.



## Why it happens

Launch concept: Launch supports Node.js 20.x, 22.x and 24.x. You choose the major version with the engines.node field in package.json. Without it, a new environment uses the current default, Node.js 24.x.

Node.js 18 was discontinued on Launch on August 1, 2025. Before that, an environment without engines.node was created on Node 18. That choice sticks: an existing environment keeps the version it was configured or defaulted with, and Launch doesn't move it to a newer major version on its own. A jump from 18 to 22 or 24 can break native modules, crypto defaults or build tooling, so Launch stops the deployment and asks you to choose instead of upgrading silently.

That explains the confusing part. The old environment fails because it is still on Node 18. The new environment works because it was created after the default changed.

Updating packages doesn't help, because dependencies don't select the runtime. Only engines.node does.

## Fix it

### Pin engines.node

Add the engines field to the package.json at the root of what Launch builds:

```json
{
  "name": "my-site",
  "engines": {
    "node": "22.x"
  }
}
```

Use a major version range such as 20.x, 22.x or 24.x. Launch keeps that major version and applies the latest minor and patch releases for it, so a range is better than an exact version like 22.18.0.

Pick the version your app runs on locally. If you were on Node 18 and want the smallest jump, start with 20.x or 22.x and test there before moving to 24.

Commit, push, and let the environment redeploy, or trigger a deployment yourself. Every environment that builds from this branch picks up the same version.

### Test the upgrade before production

A major version change is a code change, so treat it like one:

- Switch your local Node version with nvm use 22 or your version manager of choice.


- Delete node_modules, reinstall and run a production build: npm ci && npm run build.


- Push the engines change to a branch that deploys to a preview or staging environment on Launch.


- Promote to production once that environment is healthy.



Watch for native dependencies such as image processing or headless browser packages. They are the most likely to need a new version for a newer Node major.

### Move back to a previous major version

The same field works in reverse. If a feature breaks after the default moved to a newer major version, pin the previous one, for example "node": "22.x", and redeploy while you investigate. An environment without engines.node can't be rolled back to a specific version any other way.

### If you can't change the code right now

A new environment without engines.node starts on the current default. Creating one from the same branch gets you onto a supported version without a commit, but you lose the old environment's variables and settings unless you copy them over. Treat it as a stopgap and add engines.node when you can.

## Check that it worked

Print the version at the start of the build. Set the build command in the environment settings to:

```bash
node -v && npm run build
```

The first line of the build step in the deployment log shows the version, for example v22.x.y. Read it from a terminal with:

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

For the runtime version on a live SSR site, log process.version once at server start and look for it in the server logs (--type s).

## Prevent it

- Set engines.node in every project you deploy to Launch, including old ones that work today. It makes builds reproducible and turns the next Node retirement into a one-line change you make on your schedule.


- Add an .nvmrc with the same major version so local development and Launch agree.


- Review the version once a year against the [supported Node.js versions](https://www.contentstack.com/docs/developers/launch/supported-nodejs-versions) and plan the upgrade before a version is retired.


- Redeploy long-running sites now and then. Monthly patch updates only reach a project when it is redeployed.



## Key takeaways

- Node.js v18 and below are no longer supported on Launch means the environment still runs Node 18. Set engines.node to 20.x, 22.x or 24.x.


- Existing environments keep their Node version. Only new environments get the current default, Node.js 24.x.


- npm update and pnpm update don't change the runtime. engines.node does.


- Use a major range like 22.x so you keep receiving patch updates.


- Put node -v in the build command when you need to prove which version ran.





---

## npm error code E401 on Launch: install private packages

Your build fails before it compiles a single file. The deployment log stops in the dependency step with E401 and a message about a password, while npm install works fine on your laptop. Launch is trying to download a package from a private registry, and it has no credentials to do it with.

This happens with private packages on npmjs.com, GitHub Packages, Font Awesome Pro, Azure Artifacts, JFrog Artifactory and any other registry that requires a token.

## What you'll learn

- Why private package installs fail on Launch but not locally


- How to write an .npmrc that's safe to commit


- How to pass the token to the build with a Launch environment variable


- What else to check when the token is set and the error stays



## Symptoms

The deployment fails in the dependency installation step:

```text
npm error code E401
npm error Incorrect or missing password.
npm error If you were trying to login, change your password, create an
npm error authentication token or enable two-factor authentication then
npm error that means you likely typed your password in incorrectly.
...
Installing dependencies failed
Deployment failed: Please try to redeploy the site, or contact support for assistance.
```

Variations you may see:

- npm error code E401 with Unable to authenticate


- npm error code E404 for a scoped package such as @your-org/ui, when the registry hides private packages from unauthenticated requests


- npm warn deprecated lines just before the error. They are unrelated.



## Why it happens

Launch concept: every Launch build runs on a clean build machine. It clones your repository, installs dependencies and builds. Nothing from your machine comes along.

Locally, npm authenticates with a token from your user-level ~/.npmrc, written there when you ran npm login or set it up for your company registry. That file isn't in the repository, so Launch never sees it. The build machine reads only the .npmrc in your project, and if that file points a scope at a private registry without a valid token, the registry answers 401. npm turns that into "Incorrect or missing password", but there is no password involved. It means the auth token is missing.

The other common version: a project .npmrc with a token that is hard-coded, expired or revoked. That is both a build failure and a leaked secret.

## Fix it

### Commit a token-free .npmrc

Put an .npmrc at the root of what Launch builds, with a placeholder instead of the token:

```ini
# .npmrc, safe to commit
@your-org:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
```

npm replaces ${NPM_TOKEN} with the environment variable of the same name when it runs. This is the standard npm pattern for private packages in CI.

For a scope on another registry, point the scope at it and add an auth line for that host:

```ini
@your-org:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_TOKEN}
```

Every registry host needs its own _authToken line. One valid token doesn't cover a second registry.

### Set the token on the Launch environment

- Create a token with read-only access to the packages you need. On npmjs.com that is a granular or read-only access token. On GitHub Packages, a token with read:packages.


- In Launch, open the environment's Settings > Environment Variables.


- Add NPM_TOKEN (and any other names your .npmrc uses) with the token as the value. No quotes, no spaces around it.


- Save and trigger a new deployment.



Environment variables are per environment, so add the token to every environment that builds this project. Launch environment variable values are visible to everyone with access to the project. Use a read-only token scoped to the packages you need, not a personal token with publish rights.

### Remove the committed token

If the .npmrc in your repository has a real token in it, replacing it with a placeholder isn't enough. The token is still in your Git history. Revoke it at the registry, create a new one, and set the new one on Launch.

## Check that it worked

Reproduce the clean build machine locally before you push. Move your user config out of the way and install with only the project .npmrc:

```bash
NPM_TOKEN=<your-read-only-token> npm ci --userconfig /dev/null
```

If that succeeds, Launch will too. On Launch, the deployment log should move past the dependency step and print the build output. Read it with:

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

## If the token is set and E401 stays

Work through these in order:

- The variable name doesn't match. ${NPM_TOKEN} in .npmrc and NPM_TOKEN on Launch must match exactly, including case.


- The token expired or was revoked. Granular tokens on npmjs.com and many company registries expire. Generate a new one and update the variable.


- The token can't read that package. A token for one organization or scope doesn't grant access to another.


- A second registry has no token. Search .npmrc for every //host/:_authToken= line and make sure each referenced variable is set.


- The .npmrc isn't where Launch builds. In a monorepo, put it at the repository root next to the lockfile that the install uses.


- The dependency is no longer needed. Starter templates and old forks sometimes carry a private registry for a package the current version no longer uses. Removing the dependency and the .npmrc entry is a valid fix.



## Prevent it

- Never commit a real token. Add a secret scanner or a pre-commit hook that rejects _authToken= followed by anything other than ${.


- Keep the placeholder names in your .env.example so the next environment gets them too.


- Use read-only tokens with an expiry date, and put the renewal in your calendar. A token expiring is the most common reason a build that worked last month fails today.


- Run npm ci --userconfig /dev/null in your own CI so a missing token fails there first.



## Key takeaways

- npm error code E401 on Launch means a private registry rejected the install because there is no valid auth token.


- Commit an .npmrc with //host/:_authToken=${NPM_TOKEN} and set NPM_TOKEN as a Launch environment variable.


- Every registry host needs its own token line and variable.


- Revoke any token that was ever committed, even after you remove it from the file.


- Test with npm ci --userconfig /dev/null to reproduce the clean build machine locally.





---

## Invalid output directory and NoSuchKey 404s on Launch

The build log says the build succeeded. All your routes were generated. Then the deployment fails with Invalid output directory, or it goes live and the first deep link returns NoSuchKey. Both mean the same thing from Launch's side: it can't find the files it's supposed to serve where you told it to look.

This chapter covers single apps first, then single-page apps, then monorepos, where most of these problems live.

## What you'll learn

- How the Output Directory setting maps to what your build writes


- Why single-page apps return NoSuchKey on refresh and how to add a fallback


- How to deploy one app from a Turborepo or Nx monorepo


- Which package managers Launch supports



## Symptoms

- The build step finishes, then packaging fails:



```text
Warning: Invalid output directory: ./apps/web/.next
Deployment failed: Please try to redeploy the site, or contact support for assistance.
```

- The site is live, but a page returns an XML-style error:



```text
NoSuchKey: The specified key does not exist.
```

- The home page loads, but refreshing /about or opening it from a link in an email returns a 404 or NoSuchKey.


- A deployment runs for a very long time before failing with NoSuchKey, while the same build with the right settings finishes in a few minutes.


- A filtered monorepo build also builds, and fails on, an app you didn't ask for.


- The log shows npm install even though your project uses pnpm.



## Why it happens

Launch concept: each environment has a Framework Preset, a Build Command and an Output Directory. Launch runs the build command from the repository root, then packages whatever is in the output directory. Static files are served from storage, and server workloads such as Next.js SSR run from the packaged server output.

NoSuchKey is the storage layer telling you a requested file doesn't exist. Invalid output directory is the packaging step telling you the folder doesn't contain what the preset expects. Either way, the build put its files somewhere other than where Launch looks, or the files Launch needs were never produced.

## Fix it

### Match the output directory to your build

Check where your build actually writes. Run it locally and look:

```bash
npm run build && ls
```

Common values:

Framework

Output Directory

Next.js

./.next

Create React App

./build

Vite (React, Vue, Svelte)

./dist

Angular

the outputPath in angular.json, for example ./dist/my-app/browser

Gatsby

./public

Set it under the environment's Settings > Build and Output Settings, keep the Framework Preset that matches your framework, and redeploy. For a Next.js app, don't switch the preset to Other to get past an error. That serves the output as a static site, and an App Router app then returns "page does not exist" for every route.

### Add a fallback for single-page apps

A React, Vue or other client-side app with BrowserRouter-style routing has one real file: index.html. When a visitor requests /about directly, Launch looks for a file at that path, doesn't find one, and returns NoSuchKey. Navigating inside the app works, because the router handles it without a request.

Add a catch-all rewrite to launch.json at the repository root so unknown paths serve index.html:

```json
{
  "rewrites": [
    {
      "source": "/:path(.*)",
      "destination": "/index.html"
    }
  ]
}
```

Keep it as the last rewrite in the array, because rules run in order. Real files such as your JavaScript bundles and images must still load, so check the network tab after deploying. If they come back as HTML, narrow the source, for example with a negative lookahead that excludes your assets folder. [Routing with launch.json](/guides/launch-edge-functions-redirects-and-caching/routing-with-launch-json) covers the pattern syntax.

The fallback alternative is a hash router (/#/about), which never asks the server for the path. It works everywhere but changes your URLs.

### Deploy one app from a Turborepo monorepo

Launch has no root directory setting. You select the whole repository and scope the build to one app:

- Build Command: npm run build -- --filter=web


- Output Directory: ./apps/web/.next



npm run build on its own builds every app in the repository, so the filter matters. If the filtered build still pulls in, and fails on, another package, check two things:

- The filter name matches the name in the app's package.json.


- Every workspace package the app imports is declared as a dependency in that app's package.json. Turborepo scopes the build from the declared graph, and an undeclared import that resolves locally can fail on Launch.



```json
{
  "name": "web",
  "dependencies": {
    "@repo/ui": "workspace:*"
  }
}
```

### Next.js in a monorepo: build standalone output

Launch packages Next.js server workloads from Next.js standalone output. In a monorepo it expects that output inside the app's .next folder. When the deployment fails at packaging with Invalid output directory even though the path is correct and the build generated every route, the standalone build is usually missing. Turborepo's strict environment mode filters variables that aren't listed in turbo.json, which can stop the standalone build from being produced.

Set it explicitly in the app's Next.js config:

```js
// apps/web/next.config.js
module.exports = {
  output: 'standalone',
};
```

Check locally that apps/web/.next/standalone exists after npm run build -- --filter=web, then redeploy.

### Nx: keep output inside the app folder

Nx builds to dist/apps/<app> by default. Launch doesn't support build output outside the app's source directory, so change the app's outputPath:

```json
{
  "targets": {
    "build": {
      "executor": "@nx/next:build",
      "options": {
        "outputPath": "apps/my-app"
      }
    }
  }
}
```

Then use Build Command npx nx build my-app and Output Directory ./apps/my-app/.next, with the Next.js preset. Run npx nx reset before testing locally so a cached build doesn't hide the change.

### Monorepo limits to know

- launch.json inside an app folder isn't supported. Keep it at the repository root.


- Cloud Functions from an app's functions directory aren't supported in a monorepo. Use your framework's API routes instead.


- Gatsby apps inside a monorepo aren't supported.



### Use a supported package manager

Launch supports npm (the default) and yarn in node-modules mode. It reads the packageManager field in package.json to pick yarn and its version. pnpm isn't supported: Launch falls back to npm, which ignores pnpm-lock.yaml and resolves fresh versions, so a build that works locally can fail or behave differently. Yarn Plug'n'Play isn't supported either.

If you're on pnpm, generate a package-lock.json with npm install and commit it, or move the project to yarn with nodeLinker: node-modules in .yarnrc.yml.

## Check that it worked

- The deployment log reaches the packaging step without Invalid output directory.


- Request a deep link directly and check the status:



```bash
curl -sI https://your-site.contentstackapps.com/about | head -n 1
```

You want HTTP/2 200. Also request a real asset, such as your main JavaScript file, and confirm its content-type isn't text/html.

- For a monorepo, the build output in the log lists only the app you filtered to.



## Prevent it

- Write the build command and output directory into your README, so the next environment uses the same values.


- Add the SPA fallback rewrite when you create the project, not after the first broken link.


- Declare every internal workspace dependency in the consuming app's package.json.


- Set output: 'standalone' for every Next.js app in a monorepo.


- Commit one lockfile that matches a supported package manager.



## Key takeaways

- Invalid output directory and NoSuchKey mean Launch can't find the files where the Output Directory points.


- Single-page apps need a final /:path(.*) to /index.html rewrite in launch.json, or a hash router.


- In a monorepo, the filtered build command plus the app's output directory replace a root directory setting.


- Next.js apps in a monorepo need output: 'standalone'; Nx apps need their outputPath inside the app folder.


- Launch supports npm and yarn in node-modules mode. pnpm falls back to npm.



If the deployment now succeeds but the site returns CF errors or timeouts, continue with [Launch error codes decoded](/guides/launch-error-codes-decoded).



---

## Do this with AI

Install the launch-trigger-and-monitor-launch-deployments skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Launch Deploy Helper profile in MCP Profile Hub. Then ask your agent:

> Fetch the deployment log of the latest failed deployment in my production environment on Launch, don't trigger anything, and tell me which of these it is: environment variables, Node version, npm E401 or output directory.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## 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.

