---
title: "Fix it on Launch"
url: "https://developers.contentstack.com/paths/fix-it-on-launch"
type: "path_full"
level: "intermediate"
outcome: "You can diagnose a broken Launch build, decode a Launch error code and get a custom domain live."
steps:
  - "https://developers.contentstack.com/guides/published-but-my-site-still-shows-old-content"
  - "https://developers.contentstack.com/guides/fix-failing-launch-builds"
  - "https://developers.contentstack.com/guides/launch-error-codes-decoded"
  - "https://developers.contentstack.com/guides/custom-domain-stuck-on-pending-validation"
  - "https://developers.contentstack.com/guides/debug-a-failing-launch-deploy-with-an-agent"
updated: "2026-11-15T11:47:31.585Z"
---

# Fix it on Launch

- **Level:** Intermediate
- **Steps:** 5
- **Overview:** https://developers.contentstack.com/paths/fix-it-on-launch.md

---

The problems developers hit most on Contentstack Launch, from stale content and failing builds to error codes and custom domains, and how to fix each one.

**You'll end up with:** You can diagnose a broken Launch build, decode a Launch error code and get a custom domain live.

## Table of Contents

1. I published, but my site still shows old content
2. Fix failing Launch builds
3. Launch error codes decoded: CF005, CF1001, CF1004, CF003 and more
4. Custom domain stuck on Pending validation in Launch
5. Debug a failing Launch deploy with an agent


---

## Step 1: I published, but my site still shows old content

- **Source:** https://developers.contentstack.com/guides/published-but-my-site-still-shows-old-content
- **Checkpoint:** You can tell which cache layer is serving stale content.

- **Authors:** Tim Benniks
- **Published:** 2026-12-04T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:16.702Z
- **Level:** Beginner
- **Intent:** Fix
- **Tags:** headless, api

---

You hit publish, the entry shows a green status, and the page on your site still has yesterday's text. This is the most common "Contentstack is broken" moment, and Contentstack is almost never the problem. Somewhere between the publish and your browser, a layer kept the old copy.

This guide is a triage. You check one layer at a time, from the publish itself to the browser, with a command or a header for each. Most of the time you find the cause in under five minutes. It applies to any front end, with extra notes for Next.js and sites hosted on Contentstack Launch.

## What you'll learn

- How to prove whether the publish reached the Content Delivery API


- How to read cache headers to see which layer served a page


- Why a statically generated page needs a build and not a cache purge


- How to fix stale content from a CDN, a second CDN, a framework cache or the browser


- How to set things up so editors don't have to ask you again



## Symptoms

- The entry shows Published in the entry editor, but the live page shows the old value.


- The page updates after a redeploy, but not after a publish.


- The page is fresh on one URL and stale on another, for example with and without a trailing slash or a query string.


- The page is fresh in an incognito window and stale in your normal browser.


- The REST response is fresh and a GraphQL-driven page is not, or the other way around.


- Some locales update and others don't.



## Why it happens

A published entry travels through several layers before someone sees it. Each one can hold a copy:

Layer

What it holds

What clears it

Publish

The entry version on an environment and locale

Publishing to the right environment and locale

Delivery API

Contentstack's own CDN for the CDA and GraphQL

Contentstack purges it when you publish

Your build

HTML generated at build time

A new build

Framework or SDK cache

Data cached inside your app

A redeploy, or turning that cache off

Your hosting CDN

Cached pages, per URL

A purge, a redeploy, or the TTL running out

A second CDN or proxy

Its own copy of the page

Only its own purge

The browser

The page, if max-age allows it

A hard refresh, or the TTL running out

Contentstack concept: publishing makes an entry version available on one environment, in one locale. The Content Delivery API serves that version to anyone who asks with a delivery token for the same environment. Everything after the API is your stack of caches, not Contentstack's.

So the first question is always the same: does the Delivery API return the new content? If yes, the problem is in your app or your caches. If no, the problem is the publish.

flowchart TD  A[Page shows old content] --> B{Does the CDA return the new value for your environment and locale?}  B -->|No| C[Fix the publish: environment, locale, branch, token]  B -->|Yes| D{Is the page pre-rendered at build time?}  D -->|Yes| E[Trigger a build on publish with a webhook or Automate and a deploy hook]  D -->|No| F{cf-cache-status HIT with a large age?}  F -->|Yes| G[Revalidate the Launch CDN and set Cache-Control explicitly]  F -->|No| H{Is there another CDN or proxy in front?}  H -->|Yes| I[Turn off or purge caching on that layer]  H -->|No| J{Fresh in a private window?}  J -->|Yes| K[Browser cache: lower max-age]  J -->|No| L[Framework or SDK cache inside the app]## Fix it

Work through these in order. Each section starts with the check, then gives the fix.

### The content isn't published where your site reads it

This usually happens when the entry went to staging while the site reads production, or to en-us while the page renders fr-fr.

- Open the entry and check its publish status. It shows which environments and locales the entry was published to, and which version.


- Ask the Delivery API directly, with the same values your site uses:



```bash
curl -s "https://cdn.contentstack.io/v3/content_types/blog_post/entries/$ENTRY_UID?environment=production&locale=en-us" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  | jq '.entry | {title, updated_at, publish_details}'
```

- Compare publish_details.environment and publish_details.locale with what your site sends. Use your region's CDA host if your stack is not in AWS North America, for example eu-cdn.contentstack.com.



If the response has the old value, publish again to the right environment and locale. If the entry uses branches, check that the delivery token is scoped to the branch you published on. Unpublished referenced entries are a separate story, covered in [Publishing stuck or references not published](/guides/publishing-stuck-or-references-not-published). A locale that returns another locale's content is covered in [Why am I getting en-us content?](/guides/why-am-i-getting-en-us-content-locale-fallback-explained).

If the response has the new value, the publish worked. Move on.

### The page was built before you published

A statically generated page holds its content in the HTML. Publishing changes the API, not the HTML that is already on your hosting. Until something builds the site again, visitors see the old page.

Check:

- Run next build locally and look at the route table. Routes marked ○ (Static) or ● (SSG) are rendered at build time. ƒ (Dynamic) routes render on request.


- Look at the page source of the live page. If the old text is in the HTML and the page makes no Delivery API call at runtime, it came from the build.


- Check whether a redeploy fixes it. If it does, the build is your stale layer.



Fix it by rebuilding on publish. Create a deploy hook on your hosting, then call it when content changes:

- With a webhook: in your stack, add a webhook on entry publish and unpublish, and set its URL to the deploy hook.


- With Automate: trigger on entry publish and call the deploy hook, or use the Launch connector's redeploy action.



On Launch, a deploy hook is a unique URL per environment, and a POST to it starts a deployment. [Deploy from CI with the Launch CLI and API](/guides/deploy-from-ci-with-the-launch-cli-and-api) shows the setup. If your site has thousands of pages and editors publish all day, rebuilding on every publish turns into a queue. Server-render those pages and revalidate the CDN instead. [Revalidate, prime or redeploy?](/blog/revalidate-prime-or-redeploy-picking-the-right-cache-lever-on-launch) helps you pick.

### The Launch CDN serves a cached copy

For a server-rendered page, the Launch CDN keeps the response for as long as Cache-Control allows. A page with s-maxage=86400 stays cached for a day after you publish, unless you purge it.

Check the headers of the live page:

```bash
curl -sI https://www.example.com/blog/my-post | grep -iE "cache-control|cf-cache-status|x-cache|^age"
```

- cf-cache-status: HIT with a large age means the CDN served a stored copy.


- cache-control tells you how long that copy may live.


- No cache-control at all is not the same as "not cached". Set the header explicitly, so the behavior is yours and not a default.



Fix it in two parts. Purge now, from Settings > Environments > Cache in Launch, or with the Revalidate CDN Cache API by path, cache tag or hostname. Then make it automatic: revalidate on publish with the Launch connector in Automate or with a webhook route in your app. [Caching, revalidation and cache priming](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming) has the full setup, including Cache-Tag headers so one purge clears a whole section.

The cache key is the URL. /blog/my-post and /blog/my-post?utm_source=newsletter are separate entries, so purge the variant visitors actually hit, or purge by tag.

### A second CDN sits in front of Launch

Some teams keep Cloudflare, Akamai, Fastly or a WAF in front of their hosting. Launch purges its own CDN on every deployment and every revalidation. It has no way to purge yours.

Check:

- curl -sI the page and look for headers from the outer layer, such as a second age, x-cache or a vendor header.


- Request the Launch environment's default *.contentstackapps.com URL for the same path. If that is fresh and your domain is stale, the outer layer holds the old copy.



Fix it by turning caching off on the outer layer and letting Launch manage caching, which is what the Launch go-live guide recommends. If you need that layer to cache, purge it from the same webhook or automation that revalidates Launch. Layering CDNs is not recommended on Launch, partly for this reason.

### Your framework or SDK caches data

The CDA is fresh, the CDN says MISS, and the page is still old. Then the copy lives inside your app.

Check:

- Next.js App Router: a route without dynamic APIs is rendered once and reused. On Launch, the Next.js Data Cache, ISR and revalidatePath() / revalidateTag() are not supported, so code that relies on them never refreshes.


- Delivery SDK cache: if you configured cacheOptions with a persistenceStore and a cache-first policy, the SDK returns stored responses before it calls the API.


- Your own cache: an in-memory map, Redis or a fetch wrapper with a TTL.



Fix it by moving the caching decision to HTTP. Opt the route out of the framework cache and let Cache-Control and CDN revalidation handle freshness:

```typescript
// app/blog/[slug]/page.tsx
export const dynamic = 'force-dynamic';
```

Then set Cache-Control: public, max-age=0, s-maxage=86400, stale-while-revalidate for that route and revalidate on publish. For the SDK, use a network-first policy or drop cacheOptions on the server, where the CDN already caches.

### GraphQL and REST disagree

The GraphQL Content Delivery API is served and cached separately from the REST CDA. If a GraphQL-driven page is stale while the REST response is fresh, run the same query against GraphQL with the same environment and locale and compare. Most of the time the query asks for a different environment, locale or branch than you expect. If the GraphQL response itself stays old after a publish, note the time and the query and contact Contentstack Support.

### The browser kept the page

If a private window shows the new content, your browser cached the page. That happens when the page sends max-age greater than zero. Use max-age=0 for HTML and let s-maxage control the CDN. Long max-age values belong on hashed static assets, not on pages.

## Check that it worked

Run the same three checks after every fix:

- The CDA returns the new value for your environment and locale.


- curl -sI on the live URL shows cf-cache-status: MISS on the first request after the purge, and HIT with a small age after that.


- The page source contains the new text.



Then publish a small change and time how long it takes to show up. That number is what your editors experience.

## Prevent it

- Decide per route whether content lives in the build or is rendered on request, and wire the matching trigger: a deploy hook for built pages, a revalidation for rendered ones.


- Set Cache-Control explicitly on every HTML route. Never rely on a default.


- Tag responses with Cache-Tag per content type, so one revalidation clears everything that shows that content.


- Don't add a second CDN in front of Launch. If you must, turn its caching off.


- Point every environment variable for the Delivery API at the right environment, and check it in staging before you go live.


- Tell editors how long a publish takes to show up, so a two-minute build doesn't look like a bug.



## Key takeaways

- Start with the Content Delivery API. If it has the new content, the publish worked and the problem is a cache.


- Pre-rendered pages need a build. Revalidating the CDN only fetches the same old HTML again.


- cf-cache-status and age tell you whether the Launch CDN served a stored copy.


- Launch can't purge a CDN you put in front of it.


- On Launch, use Cache-Control and CDN revalidation, not the Next.js Data Cache or revalidatePath().



## Next steps

- Set up revalidation on publish with [Caching, revalidation and cache priming](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming).


- Pick the right lever per change with [Revalidate, prime or redeploy?](/blog/revalidate-prime-or-redeploy-picking-the-right-cache-lever-on-launch).


- If your build fails after you wire up a deploy hook, see [Fix failing Launch builds](/guides/fix-failing-launch-builds).





---

## Do this with AI

Install the cms-environments-publishing skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Published Content QA profile in MCP Profile Hub. Then ask your agent:

> Fetch the entry with UID blt0123456789abcdef from the blog_post content type through the Content Delivery API for the production environment and the en-us locale. Show its title, updated_at and publish_details, and tell me whether the published version matches the latest saved version.

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




---

## Frequently asked questions

### How do I know if Contentstack has the new content?

Request the entry from the Content Delivery API with the same environment, locale and delivery token your site uses. If the response has the new value, the publish worked and the stale copy lives somewhere between the API and the browser.

### Why does a redeploy fix stale content on Launch?

A deployment rebuilds the pages and purges the CDN cache for that environment. That clears both a stale static build and a stale CDN copy, which is why it always works, and why it is the most expensive fix.

### Does revalidating the Launch CDN help a statically generated page?

No. The CDN fetches the page from your build output again, and the build output still has the old content. A pre-rendered page needs a new build.

### Can a CDN in front of Launch cause stale content?

Yes. Launch purges its own CDN on every deployment and revalidation, but it can't purge a second CDN you put in front of it. Turn caching off on that layer or purge it yourself.


---

## Step 2: Fix failing Launch builds

- **Source:** https://developers.contentstack.com/guides/fix-failing-launch-builds
- **Checkpoint:** Your build passes with the right env vars, Node version and output directory.

- **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

---

> **Full guide available:** [View all 4 chapters in one document](https://developers.contentstack.com/guides/fix-failing-launch-builds/full.md)

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.





---

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


---

## Step 3: Launch error codes decoded: CF005, CF1001, CF1004, CF003 and more

- **Source:** https://developers.contentstack.com/guides/launch-error-codes-decoded
- **Checkpoint:** You can map a CF error code to its cause and fix.

- **Authors:** Tim Benniks
- **Published:** 2026-12-05T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:05.340Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** headless, api, next

---

Launch returns its own error codes when a request fails at the edge or at your origin. The page shows a short message like Request Timeout CF005 and a status code, and that code tells you exactly which limit you hit or which part of your app failed. Once you know the table, most of these errors take minutes to fix.

This guide is a reference for every public Launch response error code, followed by deeper sections on the ones that come up most: timeouts, body and header limits, oversized response headers, raw RSC payloads in Next.js and the "warming up" screen. The examples use Next.js, but the codes and limits apply to every framework on Launch.

## What you'll learn

- What each Launch error code means and which layer returns it


- Which platform limit sits behind CF005, CF1001, CF1004 and CF003


- How to measure request and response headers so you can see the problem


- How to fix a Next.js page that shows raw RSC data instead of HTML


- What the "warming up" screen is and when it shows up



## Symptoms

Code

Status

Layer

What it means

CFL-0001

500

CDN edge

Your edge function threw an exception or returned an invalid response

CF001

500

Origin

The server process failed to start

CF002

500

Origin

An internal Launch error. Retry, then contact support if it persists

CF003

502

Origin

The response headers are larger than the platform limit

CF004

500

Origin

The origin ran but returned no valid HTTP response

CF1001

413

Origin

The request body is larger than 5 MB

CF1002, CF1003

502

Origin

The path or query string isn't a valid URL under RFC 3986

CF1004

413

Origin

The request headers, usually cookies, are larger than the platform limit

CF005

504

Origin

The origin didn't respond within the request timeout

The messages you see look like this:

```text
Internal Server Error CF001: The server failed to start. Check the Launch Server logs for details.
Bad Gateway CF003: The total size of the response headers exceeded the limit. Check and reduce their size.
Internal Server Error CF004: No valid response from the server. Check the Launch Server Logs and try again.
The request body exceeds the maximum allowed size of 5 MB.
```

## Why it happens

Launch concept: a request first reaches the CDN edge, where edge functions, redirects and rewrites run. If it isn't served from cache, it goes to the origin: your SSR server or Cloud Function. Codes that start with CFL- come from the edge. Codes that start with CF come from the origin.

That split tells you where to look. An edge error means your functions/[proxy].edge.js failed. An origin error means your app failed to start, failed to answer, or sent or received something larger than the platform accepts. The limits that matter here:

Limit

Value

Request headers

About 10 KB, varies slightly per cloud provider

Request body

5 MB (CF1001; the platform limits page lists 128 KB, so test large bodies before you rely on them)

Response headers

32 KB

Response body

5 MB

Request timeout

30 seconds by default, up to 13 minutes on request

Every error has evidence in the server logs. Open the environment in Launch and check Server Logs, or pull them from the terminal with csdx launch:logs --type s. Logs are kept for 24 hours, so forward them with Log Targets if you need history. [Logs, debugging and limits](/guides/launch-edge-functions-redirects-and-caching/logs-debugging-and-limits) covers both.

## Fix it

### CF005: the request timed out

CF005 returns a 504 when your origin doesn't answer in time. The default request timeout is 30 seconds for every organization. It applies to both buffered and streaming responses.

This usually happens for one of four reasons:

- A slow downstream call: an external API, a search index or a database that takes 20 seconds on a bad day.


- A long job inside a request, such as generating a PDF or importing a file.


- An exception that left the request hanging without a response.


- Memory pressure that makes every request slower.



Find the slow part first. Log the duration of every external call in the route:

```typescript
// app/api/search/route.ts
export async function GET(request: Request) {
  const started = Date.now();
  const response = await fetch(`${process.env.SEARCH_URL}?q=${new URL(request.url).searchParams.get('q')}`, {
    signal: AbortSignal.timeout(8000),
  });
  console.log(JSON.stringify({ route: '/api/search', upstreamMs: Date.now() - started, status: response.status }));

  if (!response.ok) {
    return Response.json({ error: 'search unavailable' }, { status: 502 });
  }
  return Response.json(await response.json());
}
```

AbortSignal.timeout() gives the upstream call a budget below the platform timeout, so you return a clear error instead of a 504.

Then pick a fix:

- Make it faster. Cache the upstream result, fetch in parallel with Promise.all, and request only the fields you need.


- Move it out of the request. For work that is long by nature, start a background job, return 202 right away, and let the client poll for the result.


- Stream the response. In Next.js, enable streaming response mode in the project's build settings so the shell is sent while slower parts load.


- Ask for a longer timeout. Your Contentstack representative can raise it up to 13 minutes. The response must still start within 98 seconds, and a fully buffered response must finish within those 98 seconds. The new value applies from your next deployment, not to deployments that are already running.



### CF1001: the request body is larger than 5 MB

CF1001 returns 413 when a single request body exceeds 5 MB. It shows up with file uploads that go through your own API route, large form posts and Next.js Server Actions that receive files.

Don't send files through your app. Upload them straight from the browser to storage with a signed upload URL, and send only the reference to your route. If your payload is large JSON, remove fields the server doesn't need or split the request.

Next.js has its own, lower limit for Server Actions: 1 MB by default, set with experimental.serverActions.bodySizeLimit in next.config.js. Raising it above 5 MB doesn't help on Launch, because the platform rejects the request first.

### CF1004: the request headers are too large

CF1004 returns 413 when the request headers together exceed the limit, which is about 10 KB. Cookies are almost always the cause. Analytics, consent, A/B testing and auth libraries each add their own, and some store whole JSON objects.

The pattern is easy to spot: the site works in a private window and fails in your normal browser, or it fails for returning visitors only.

Measure what the browser sends. In the DevTools console on the failing site, this prints the size of the cookies that JavaScript can read, which is a lower bound:

```javascript
new Blob([document.cookie]).size
```

For the full picture, including HttpOnly cookies, open the failing request in the Network tab and check the Cookie request header.

Then trim:

- Store session data on the server and keep only an ID in the cookie.


- Set cookies on the narrowest Path and domain that works, so they aren't sent with every request.


- Remove cookies from tools you no longer use, and expire old ones.


- Check tag managers and third-party scripts that write large cookies on every page.



Some proxies and servers report oversized headers as 431 Request Header Fields Too Large. That is the generic HTTP status for the same problem. On Launch, the code you see is CF1004 with a 413.

### CF003: the response headers are larger than 32 KB

CF003 returns 502 when your app's response headers add up to more than 32 KB. Large Set-Cookie headers are one cause. The sneaky one is a header that grows with content.

A Link header with hreflang alternates is the classic example. A product page in 60 markets lists 60 full URLs in one header. If the slugs are non-ASCII, such as Thai or Japanese, each one is percent-encoded and can be several times longer than its English version. The English page passes, the Thai page returns CF003, and it looks like a locale bug.

Measure the real headers, not the error response. When the limit is hit, Launch replaces your response with a small 502, so measuring the live URL shows tiny headers. Run the app locally and request it over HTTP/1.1, since HTTP/2 compresses headers:

```bash
npm run build && npm run start &
curl -s --http1.1 -D - -o /dev/null http://localhost:3000/th/products/some-product | wc -c
```

Then fix the header that grows:

- Move hreflang alternates from the Link header into <link rel="alternate"> tags in the HTML <head>, or into your XML sitemap. Search engines accept all three.


- Remove large custom headers that carry tokens or debug data.


- Collapse cookies into fewer, smaller Set-Cookie headers.



### CF001, CF004 and CFL-0001: the code failed

These three mean your code didn't produce a response.

- CF001: the server didn't start. Check the server command and the build output directory, start the production build locally with the same command, and look for an out-of-memory crash in the logs.


- CF004: the server started but returned nothing valid. Usually an unhandled rejection after a failed fetch. Wrap data fetching so every path returns a response with a status code.


- CFL-0001: the edge function failed. The edge runtime is not Node.js, so process is not defined and other Node APIs throw there. Read environment variables from context.env, and always return a Response. [Edge functions in practice](/guides/launch-edge-functions-redirects-and-caching/edge-functions-in-practice) covers the runtime.



### CF1002 and CF1003: the URL isn't valid

These return 502 when the path or query string breaks RFC 3986. Unescaped spaces, #, % or ? in a path are the usual cause, often from search forms or links built by string concatenation. Build URLs with URL and URLSearchParams, which encode for you:

```typescript
const url = new URL('/search', 'https://www.example.com');
url.searchParams.set('q', 'cats & dogs 100%');
// https://www.example.com/search?q=cats+%26+dogs+100%25
```

### Raw RSC data instead of HTML after navigation

This one has no error code. In a Next.js App Router app, a page suddenly shows raw, numbered lines of JSON-like data instead of the rendered page. Reloading doesn't help, and it hits every visitor of that URL.

It happens when a client-side navigation hits a redirect:

- Next.js requests the next page with an Rsc: 1 header and an _rsc query parameter.


- The route redirects, and the browser follows it. It keeps the Rsc: 1 header and drops _rsc.


- Next.js sees Rsc: 1 on the new URL and returns the RSC payload.


- The CDN caches that payload under the plain URL, because the query parameter is gone. Every later visitor gets it.



Fix it with an edge function that removes the Rsc header when _rsc is missing:

```javascript
// functions/[proxy].edge.js
export default function handler(request, context) {
  const url = new URL(request.url);
  const hasRscHeader = request.headers.get('rsc') === '1';
  const hasRscParam = url.searchParams.has('_rsc');

  if (hasRscHeader && !hasRscParam) {
    const modified = new Request(request);
    modified.headers.delete('rsc');
    return fetch(modified);
  }

  return fetch(request);
}
```

Launch's own documentation limits the check to a list of affected paths. Applying it to every path is also safe, because a real RSC request always carries both. After you deploy, the bad copy may still be cached, so revalidate the affected paths as shown in [Caching, revalidation and cache priming](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming).

### The "warming up" screen after idle

An environment that gets no traffic for a while scales down. The next visitor sees a "warming up" page that reloads by itself once the environment is ready, usually within a few seconds. Production sites with steady traffic don't reach this state.

You mostly see it on staging, preview and demo environments, and on Live Preview first thing in the morning. If that matters, keep the environment warm with a scheduled request to a cheap route, for example from Automate or a scheduled CI job:

```typescript
// app/api/health/route.ts
export async function GET() {
  return Response.json({ status: 'ok' }, { headers: { 'Cache-Control': 'no-store' } });
}
```

## Check that it worked

- Request the failing URL with curl -i and confirm the status and body are your app's, not a Launch error message.


- For CF003, re-measure headers locally over HTTP/1.1 for the largest locale or page.


- For CF005, check the server logs for the route's duration over the next hour of real traffic.


- For the RSC problem, open the page in a private window after the revalidation and view the source. It should be HTML.



## Prevent it

- Give every external call a timeout below the platform's 30 seconds.


- Upload files directly to storage with signed URLs. Never post them through your own route.


- Keep cookies small and keep session data on the server.


- Put hreflang alternates in HTML or the sitemap, not in a response header.


- Keep the RSC edge function deployed on any Next.js App Router site that uses redirects.


- Forward logs with Log Targets, so you still have the evidence when someone reports an error a day later.



## Key takeaways

- CFL- codes come from the edge, CF codes from the origin.


- CF005 is the 30-second timeout. Make the work faster, move it out of the request, stream, or ask for a higher ceiling.


- CF1001 is a body over 5 MB, CF1004 is headers over about 10 KB, and CF003 is response headers over 32 KB.


- Measure response headers locally over HTTP/1.1, because the live error response hides the real size.


- Raw RSC data after a navigation is a cached redirect response. Strip Rsc: 1 when _rsc is missing, then revalidate.



## Next steps

- Read logs and learn the remaining limits in [Logs, debugging and limits](/guides/launch-edge-functions-redirects-and-caching/logs-debugging-and-limits).


- If the deployment itself fails before any request, start with [Fix failing Launch builds](/guides/fix-failing-launch-builds).


- Let an agent read the logs for you with [Debug a failing Launch deploy with an agent](/guides/debug-a-failing-launch-deploy-with-an-agent).





---

## Do this with AI

Install the launch-platform 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:

> My production environment on Launch returns 504 CF005 on /api/search since the last deployment. Pull the server logs for that path from the last hour, list the slowest requests and any errors around them, and suggest what to change. Don't trigger a deployment.

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




---

## Frequently asked questions

### What does CF005 mean on Launch?

The origin didn't respond within the request timeout, which is 30 seconds by default. Launch returns a 504 with the CF005 message.

### What is the difference between CF1001 and CF1004?

Both return 413. CF1001 means the request body is larger than 5 MB. CF1004 means the request headers, usually cookies, are larger than the platform allows.

### Why does a page return 502 CF003 on some URLs but not others?

CF003 fires when the response headers add up to more than 32 KB. Headers that grow with content, such as a Link header with many hreflang alternates, push some pages over the limit and not others.

### Where do CFL errors come from?

CFL-0001 comes from the CDN edge, which means your edge function threw or returned an invalid response. CF codes come from the origin, your server or Cloud Function.

### Can I raise the 30 second timeout?

Yes, up to 13 minutes, by asking your Contentstack representative. The response must still start within 98 seconds, and the new value applies from your next deployment.


---

## Step 4: Custom domain stuck on Pending validation in Launch

- **Source:** https://developers.contentstack.com/guides/custom-domain-stuck-on-pending-validation
- **Checkpoint:** Your custom domain and certificate are live.

- **Authors:** Tim Benniks
- **Published:** 2026-12-06T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:49.281Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** headless, security

---

You added a custom domain to a Launch environment, copied the records into your DNS provider, and both Domain Status and Certificate Status stay on Pending. Hours later they still do. Or the domain went Active, you switched traffic, and the browser shows a certificate warning.

In almost every case the cause is in DNS: a record of the wrong type, a name your provider rewrote, a CAA record that blocks the certificate authority, or a proxy that sits between visitors and Launch. This guide goes through each one, with a dig command to prove it. It's for anyone moving a site to Launch, especially a live site where downtime isn't an option.

## What you'll learn

- Which three DNS records Launch needs and in what order to add them


- Why the certificate record must be a CNAME, not a TXT


- How CAA records, apex domains and multi-level subdomains block validation


- What to do when Cloudflare or another proxy sits in front of Launch


- How to redirect between apex and www without losing the query string



## Symptoms

- Domain Status or Certificate Status shows Pending in Settings > Environments > Domains and doesn't change.


- A status shows Error. Hovering it shows a message and an error code.


- The apex domain loads, but www doesn't, or the other way around.


- The domain is Active, but browsers report a certificate for a different name.


- Visitors see a Cloudflare error page, such as Error 1000 or Error 1014, after you point a proxy at Launch.


- A redirect from the apex to www drops the utm_ parameters from campaign links.



Hover the Pending or Error status and copy the message. It often names the problem directly, for example a CAA record or a missing validation record.

## Why it happens

Launch concept: a custom domain needs three DNS records, added in two steps. Launch shows all of them in the domain's Edit modal.

Record

Type

Purpose

When to add it

Hostname validation

TXT

Proves you own the domain

First

Certificate validation (DCV)

CNAME

Lets the certificate authority issue an SSL certificate

First

DNS record

CNAME for a subdomain, A for an apex

Routes visitors to Launch

After both statuses are Active

With automatic SSL, Launch issues and renews the certificate through an ACME certificate authority such as Let's Encrypt. That authority checks the DCV record before it issues anything. Without that record in the right shape, the certificate waits forever.

The order matters for live sites. If you add the TXT and DCV records while the old host still serves traffic, Launch validates the domain and issues the certificate in the background. When you then switch the CNAME or A record, the certificate is already there, and nobody sees a warning.

sequenceDiagram  participant You  participant DNS as Your DNS provider  participant Launch  participant CA as Certificate authority  You->>Launch: Add custom domain  Launch-->>You: TXT, DCV CNAME and DNS record values  You->>DNS: Add TXT and DCV CNAME  Launch->>DNS: Check TXT  CA->>DNS: Check DCV CNAME and CAA  CA-->>Launch: Certificate issued  Launch-->>You: Domain and certificate Active  You->>DNS: Add CNAME or A record to switch traffic## Fix it

Start by checking what DNS actually returns. Your provider's dashboard shows what you typed, and dig shows what the world sees. The causes below are ordered from most to least common.

### The DCV record was added as a TXT

The hostname validation record is a TXT, so it is natural to add the second record as a TXT too. The certificate validation record is a CNAME. As a TXT it does nothing, and the certificate stays on Pending.

Check both records, using the exact names from the Launch UI:

```bash
dig TXT _cf-custom-hostname.www.example.com +short
dig CNAME _acme-challenge.www.example.com +short
```

The names above are examples. Copy the Name and Value that Launch shows for your domain rather than assuming them. The CNAME lookup must return the value from the Certificate Validation Record section. If it returns nothing and a dig TXT on the same name returns that value, delete the TXT and create a CNAME.

Then open the domain's Actions menu in Launch and choose Revalidate. Use Refresh at the top of the list if the status doesn't update.

### Your DNS provider changed the record name

Many DNS providers append the zone to every name you enter. If you type _acme-challenge.www.example.com into the example.com zone, the record becomes _acme-challenge.www.example.com.example.com. Validation looks at the right name and finds nothing.

Check with the doubled name:

```bash
dig CNAME _acme-challenge.www.example.com.example.com +short
```

If that returns your value, rename the record to _acme-challenge.www, without the zone.

Multi-level subdomains follow the same rule. For shop.eu.example.com in the example.com zone, the routing record name is shop.eu and the DCV name is _acme-challenge.shop.eu. If eu.example.com is delegated to its own zone, for example at a different provider, add the records in that zone instead. A record added to the parent zone is never seen once a subzone is delegated.

### A CAA record blocks the certificate authority

A CAA record lists which certificate authorities may issue certificates for a domain. Authorities check it before issuing, and they walk up the tree: a CAA record on example.com also applies to www.example.com and shop.eu.example.com.

If your security team set CAA to allow only your current CA, the certificate for Launch can't be issued. The status hover usually mentions CAA when this happens.

```bash
dig CAA www.example.com +short
dig CAA example.com +short
```

If either returns entries and none of them is the authority Launch uses, add one next to the existing entries. Don't remove the others, or you'll break certificates elsewhere. For Let's Encrypt:

```text
example.com.  3600  IN  CAA  0 issue "letsencrypt.org"
```

Confirm the authority with the message in the status hover, then revalidate the domain. If you upload a custom certificate instead of using automatic SSL, no DCV record is needed, and CAA only has to allow the authority that issued your certificate.

### The apex domain is set up like a subdomain

An apex domain, such as example.com, can't have a CNAME in standard DNS. Launch gives you an A record for the apex instead. Copy the IP address from the DNS Record section of the Edit modal, and remove any old A or AAAA records for the apex that still point at your previous host. A leftover record sends some visitors to the old server.

Two more things trip people up:

- www is a separate domain. Launch only serves hostnames you added to the environment. If example.com works and www.example.com doesn't, add www too, with its own records.


- Redirect options create domains. When you add an apex with Add [www.apex.com](http://www.apex.com) (subdomain) and redirect apex domain to it, Launch creates two domains. Each needs its own TXT and DCV records before it goes Active.



If you hit an error while adding a domain, check your plan's domain limit. The number of custom domains per environment and per project depends on your plan, redirect domains included. Contact Contentstack Support to raise it.

### A proxy or CDN sits in front of Launch

Launch runs on Cloudflare and includes its own CDN, WAF and DDoS protection. Putting another proxy in front is not recommended, but when you do, it changes how validation and routing work.

Your DNS is in a Cloudflare zone. If the record to Launch is proxied (orange cloud), traffic flows from your Cloudflare zone into Launch's. That needs Cloudflare Orange-to-Orange (O2O):

- Create a CNAME for your custom domain that points to the value Launch gives you.


- Keep it proxied.


- Ask your Cloudflare account team to enable Orange-to-Orange.



Without O2O, visitors get Cloudflare errors such as 1014 instead of your site. If you don't need your own Cloudflare features on this hostname, set the record to DNS only (grey cloud) instead.

Another proxy, such as a WAF or a different CDN. Cloudflare Error 1000 ("DNS points to prohibited IP") usually means the proxy forwards to the default *.contentstackapps.com domain, which resolves to Cloudflare addresses. Fix it like this:

- Add the public hostname as a custom domain in Launch and validate it with the TXT and DCV records.


- Point the proxy's origin at the CNAME target Launch shows for that domain.


- Forward the Host header for that custom domain. Launch routes to the right environment by host.


- Turn caching off on the proxy. Launch purges its own CDN on every deployment, and can't purge yours. See [I published, but my site still shows old content](/guides/published-but-my-site-still-shows-old-content).



Firewall rules and DDoS protection then live on your proxy, because traffic reaches Launch through it.

### The redirect drops the query string or goes the wrong way

The apex redirect options in Launch go from the apex to a subdomain, or to another domain in the same environment, with a 301, 302, 307 or 308. Test what your redirect does with a real campaign URL:

```bash
curl -sI "https://example.com/pricing?utm_source=newsletter" | grep -i -E "^HTTP|^location"
```

The location header should keep the path and the query string. If it doesn't, or you need the opposite direction, such as www to the apex, add both domains to the environment without a UI redirect and handle the redirect in an edge function:

```javascript
// functions/[proxy].edge.js
export default function handler(request, context) {
  const url = new URL(request.url);

  if (url.hostname === 'www.example.com') {
    url.hostname = 'example.com';
    return Response.redirect(url.toString(), 308);
  }

  return fetch(request);
}
```

Changing hostname on a URL keeps the path and every query parameter. Redirect sources in launch.json can't match a hostname, which is why this belongs in an edge function. [Edge functions in practice](/guides/launch-edge-functions-redirects-and-caching/edge-functions-in-practice) covers routing by hostname in more depth.

## Check that it worked

- Both Domain Status and Certificate Status show Active in Launch.


- The routing record resolves to the value Launch gave you:



```bash
dig www.example.com +short
dig A example.com +short
```

- The certificate covers the hostname:



```bash
curl -svI https://www.example.com 2>&1 | grep -i -E "subject:|issuer:|^< HTTP"
```

- Every hostname you serve answers with your site, and every redirect keeps the path and query string.



DNS changes can take up to 48 hours to reach everyone, depending on your provider and TTLs. If dig against a public resolver such as dig @1.1.1.1 returns the right values and Launch still shows Pending, use Revalidate.

## Prevent it

- Add the TXT and DCV records days before go-live, so the certificate exists before you switch traffic.


- Lower the TTL on the records you will change at cutover a day ahead, and raise it again afterwards.


- Keep a CAA entry for the authority Launch uses, and tell your security team why it's there.


- Add every hostname you serve, including www, as its own custom domain.


- Avoid a proxy in front of Launch. If you need one, use O2O for Cloudflare zones and forward the Host header for anything else.


- Copy record names and values from the Launch UI every time. They differ per domain.



## Key takeaways

- A custom domain needs a TXT for ownership, a CNAME for the certificate, and then a CNAME or A record for traffic.


- The DCV record is a CNAME. As a TXT, the certificate never leaves Pending.


- Check what DNS returns with dig, including doubled names like _acme-challenge.www.example.com.example.com.


- CAA records on a parent domain apply to every subdomain. Add the Launch authority without removing your others.


- Cloudflare in front of Launch needs Orange-to-Orange. Other proxies need the custom domain as origin and the right Host header.


- Use an edge function for www to apex redirects and anything that must keep the full query string.



## Next steps

- Plan your redirects and rewrites with [Routing with launch.json](/guides/launch-edge-functions-redirects-and-caching/routing-with-launch-json).


- If the domain is live but requests fail, look the code up in [Launch error codes decoded](/guides/launch-error-codes-decoded).


- Let an agent check your deployment and logs with [Debug a failing Launch deploy with an agent](/guides/debug-a-failing-launch-deploy-with-an-agent).





---

## Do this with AI

Install the launch-platform 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:

> List the custom domains on my production Launch environment with their domain and certificate status. For any that are Pending or Error, show the DNS records Launch expects, and give me the dig commands to check each one. Don't change any domain settings.

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




---

## Frequently asked questions

### Should the certificate validation record be a TXT or a CNAME?

A CNAME. The hostname validation record is a TXT, but the certificate validation (DCV) record is a CNAME. Adding the DCV record as a TXT leaves the certificate on Pending.

### How long does custom domain validation take?

Once the records resolve, Launch validates the domain and issues the certificate on its own. DNS changes can take up to 48 hours to propagate, depending on your provider and TTLs.

### Do I point my domain at Launch before validation?

No. Add the TXT and DCV records first and wait until the domain and certificate are Active. Then add the CNAME or A record that routes traffic, so the certificate is ready at cutover.

### Why does a CAA record block my certificate?

A CAA record lists the certificate authorities allowed to issue for a domain. If yours doesn't include the authority Launch uses, the certificate can't be issued. Add that authority next to your existing entries.

### Can I put Cloudflare in front of Launch?

It is not recommended. If your DNS lives in a Cloudflare zone and you proxy the record, Cloudflare Orange-to-Orange has to be set up. Other proxies must forward the Host header and should not cache.


---

## Step 5: Debug a failing Launch deploy with an agent

- **Source:** https://developers.contentstack.com/guides/debug-a-failing-launch-deploy-with-an-agent
- **Checkpoint:** An agent can pull logs and diagnose a failed deploy for you.

- **Authors:** Tim Benniks
- **Published:** 2026-12-19T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:50.848Z
- **Level:** Intermediate
- **Intent:** Fix
- **Tags:** ai, agent_skills, mcp, next

---

A Launch deployment fails, and the answer is somewhere in a few hundred lines of build log. Reading that log is exactly the kind of work an agent is good at, as long as it can reach the log and knows what Launch errors mean. With the Launch skills and the Launch Deploy Helper profile it can do both, and it can redeploy for you once you've fixed the cause and said yes.

This guide walks through one real failure on a Next.js App Router project, prompt by prompt, and shows which tools the agent calls at each step.

## What you'll learn

- What you need connected before you start


- How the agent finds the failed deployment and reads its build log


- How it maps a log line to a cause and a fix


- How the redeploy works, and where you approve it


- What the Deploy Helper profile can't do, and what to use instead



## Symptoms

The deployment shows FAILED in Launch, or your CI job that watches Launch fails. In this example, the build log ends with:

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

The same commit builds fine locally and on another host. That detail matters, and the agent will use it.

## Set up the agent

You need two things from [set up your AI workbench for Contentstack](/guides/set-up-your-ai-workbench-for-contentstack):

- The skills. launch-trigger-and-monitor-launch-deployments knows the deployment statuses and the safe trigger, poll and diagnose loop. launch-platform knows Launch builds, environment variables, Node versions and output settings. The first one only runs when you call it by name. In Claude Code, that's /contentstack-skills:launch-trigger-and-monitor-launch-deployments.


- The Launch Deploy Helper profile. Connect it with profile_id=launch_deploy_helper on the Profile Hub URL, and pick your Launch project at sign-in, or add launch_project_uid=<uid> to the URL.



```bash
claude mcp add --transport http launch-deploy \
  "https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=launch_deploy_helper"
```

Launch Deploy Helper has ten tools:

Tool

What it does

Asks before running?

get_all_projects, get_all_environments

Find the project and environment

No

get_all_deployments, get_deployment

List deployments and read one deployment's status

No

get_latest_live_deployment

Show what is serving traffic now

No

get_deployment_logs

Read the build and deployment log

No

get_deploy_hooks

List deploy hooks

No

create_deployment

Deploy the latest commit of the environment's branch

Yes

trigger_deploy_hook

Run an existing deploy hook

Yes

revalidate_cdn_cache

Revalidate the environment's CDN cache

Yes

It can't edit environments, environment variables or projects. That limit shapes the rest of this example.

## Step 1: find the failed deployment and read the log

Ask for a diagnosis only:

> The latest deployment of my-site on production failed. Find it, read its build log and tell me the most likely cause. Don't trigger anything.

The agent works through the read-only tools. A trace looks like this:

```text
get_all_projects                 -> my-site
get_all_environments             -> production (branch: main)
get_all_deployments  limit=5     -> latest: FAILED, commit 4e1c9a2
get_latest_live_deployment       -> previous deployment still LIVE
get_deployment_logs              -> 412 log entries
```

Each log entry has a message, a timestamp and a stage, so the agent can see whether the failure happened while installing, building or deploying. If the log is long, it pages through with the timestamp argument.

Note the fourth call. A failed deployment doesn't replace the live one, so your site is still serving the previous build. That tells you how urgent this is.

## Step 2: map the error to a cause

The agent comes back with something like:

> The build fails while Next.js prerenders /, /_not-found and /articles. Error: Invalid URL during prerendering usually means code calls new URL() with a value that is undefined at build time. lib/contentstack.ts builds the API base URL from process.env.NEXT_PUBLIC_SITE_URL. That variable is in your .env.example, but nothing in the log shows it being set, and the same commit builds where it is set. Most likely cause: NEXT_PUBLIC_SITE_URL is missing from the production environment in Launch.

That's the launch-platform skill doing its job. It knows that Next.js reads environment variables at build time for prerendered pages, so a variable that only exists at runtime, or not at all, breaks the build and not the running site. The full set of causes for this symptom is in [environment variables undefined or deploy stuck](/guides/fix-failing-launch-builds/env-vars-undefined-or-deploy-stuck).

Other log lines map to other chapters of [fix failing Launch builds](/guides/fix-failing-launch-builds). Ask the agent to name the chapter when it gives you a cause:

Log line points at

Read

An unsupported Node.js version, or a missing engines.node

[Node version errors](/guides/fix-failing-launch-builds/node-version-errors)

E401 or 404 from npm for a private package

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

An invalid or missing output directory, or a monorepo path

[Output directory, monorepos and 404s](/guides/fix-failing-launch-builds/output-directory-monorepos-and-404s)

A Launch error code on a live deployment

[Launch error codes decoded](/guides/launch-error-codes-decoded)

## Step 3: fix it

The agent proposes two changes:

- Add NEXT_PUBLIC_SITE_URL to the production environment in Launch.


- Fail early with a clear message when the variable is missing, so the next miss doesn't surface as Invalid URL:



```ts
const siteUrl = process.env.NEXT_PUBLIC_SITE_URL;

if (!siteUrl) {
  throw new Error('NEXT_PUBLIC_SITE_URL is not set. Add it to the Launch environment.');
}

export const apiBase = new URL('/api', siteUrl);
```

The first change is yours to make. Launch Deploy Helper can't edit environment variables, on purpose. Add the variable in the environment's settings in Launch. If you want an agent to compare your .env.example with the Launch environment, the launch-sync-environment-variables-from-env-example skill does that, but it needs a profile or API access that can update environments, so keep it out of this read-mostly setup.

The second change goes in your repo. Commit and push it to the environment's branch.

## Step 4: redeploy after you approve

Now ask for the deployment:

> I added NEXT_PUBLIC_SITE_URL to production and pushed the guard to main. Redeploy production and watch it until it's live or failed.

The deployment skill names the project and environment and asks you to confirm. Your client asks again before it runs create_deployment, because the tool is marked destructive. Approve it, and the agent polls:

```text
create_deployment  environment=production   -> new deployment, QUEUED
get_deployment                              -> DEPLOYING
get_deployment                              -> DEPLOYING
get_deployment                              -> LIVE
```

The skill polls every 10 seconds and stops on LIVE, FAILED, CANCELLED or SKIPPED. If the new deployment fails, it reads the new log and you're back at step 2 with a different error.

Two things to know about create_deployment:

- It deploys the latest commit of the environment's configured branch. Push your fix before you ask for the redeploy, or the agent deploys the old code again.


- It can't deploy a specific commit or roll back. The Launch API can: its deployment endpoint takes a commit hash, and it has a rollback endpoint. See [deploy from CI with the Launch CLI and API](/guides/deploy-from-ci-with-the-launch-cli-and-api).



## When the build passes but the site errors

Some failures only appear after the deployment is live: a 502, a function timeout, a Launch error code in the browser. Those are in the server logs, and Launch Deploy Helper doesn't read server logs.

You have two options. The Launch product profile (profile_id=launch) includes the server log tool, but it also creates and deletes projects and environments. The narrower option is a custom profile in the MCP Profile Hub app with Deploy Helper's tools plus get_server_logs. The server log tool takes a start and end time, so give the agent the time window:

> Read the server logs for the live production deployment between 14:00 and 14:30 UTC today and group the errors by message.

Then match the codes against [Launch error codes decoded](/guides/launch-error-codes-decoded), and see [logs, debugging and limits](/guides/launch-edge-functions-redirects-and-caching/logs-debugging-and-limits) for how Launch logging works. I explain why I'd build that custom profile instead of connecting the broad one in [pick the right Profile Hub profile for the job](/blog/pick-the-right-profile-hub-profile-for-the-job).

## Check that it worked

- Ask the agent for get_latest_live_deployment. It should show the new deployment UID and your fix commit.


- Open the pages that failed to prerender (/, /articles) and check they render with real content.


- If you changed content-dependent pages and the site still shows the old version, ask the agent to run revalidate_cdn_cache for the environment. It asks first, like any destructive tool.



## Prevent it

- Keep .env.example complete, and check new variables against the Launch environment before you merge.


- Validate required environment variables at startup or build time, with a clear error, instead of letting new URL(undefined) fail.


- Pin engines.node in package.json so the build doesn't depend on Launch's default Node version.


- Keep Launch Deploy Helper as your everyday Launch profile. Reach for a broader one only for the task that needs it, and disconnect it afterwards.



## Key takeaways

- With the Launch skills and the Launch Deploy Helper profile, an agent can go from "deploy failed" to a named cause using only read-only tools: get_all_deployments, get_deployment and get_deployment_logs.


- Ask for a diagnosis first, with "don't trigger anything" in the prompt. Approve deployments as a separate step.


- create_deployment deploys the latest commit of the environment's branch, so push the fix first.


- Deploy Helper reads build logs, not server logs, and can't change environment variables. Use a custom profile with get_server_logs for runtime errors, and fix variables in Launch yourself.


- Every deployment needs your approval twice: once from the skill, once from your client.





---

## Do this with AI

Install the launch-trigger-and-monitor-launch-deployments and launch-platform skills 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:

> The latest deployment of my Launch project's production environment failed. Find it, read its build log, and tell me the most likely cause and which file or setting to change. Don't trigger a deployment.

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




---

## Frequently asked questions

### Which Profile Hub profile do I need to debug Launch deployments?

Launch Deploy Helper. It lists projects, environments and deployments, reads build logs, and can trigger a new deployment or a cache revalidation. It can't change projects or environments.

### Can the agent read runtime logs as well as build logs?

Not with Launch Deploy Helper, which only reads deployment logs. For server logs, use a custom profile that adds the server log tool, or the Launch product profile.

### Will the agent redeploy without asking?

No. Deployment tools are marked destructive, so clients ask before running them, and the Launch deployment skill requires your explicit approval before every deployment.

### Which commit does a redeploy through the agent use?

The create deployment tool deploys the latest commit of the environment's configured Git branch. To deploy a specific commit or roll back, use the Launch API or CLI.

