Do this with AI
Install the launch-trigger-and-monitor-launch-deployments and launch-platform skills from 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 first.
Debug a failing Launch deploy with an agent
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:
Error: Invalid URL
Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error
> Export encountered errors on following paths:
/
/_not-found
/articlesThe 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:
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.
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:
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 entriesEach 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.
Other log lines map to other chapters of 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 | |
E401 or 404 from npm for a private package | |
An invalid or missing output directory, or a monorepo path | |
A Launch error code on a live deployment |
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:
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:
create_deployment environment=production -> new deployment, QUEUED
get_deployment -> DEPLOYING
get_deployment -> DEPLOYING
get_deployment -> LIVEThe 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.
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, and see 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.
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.
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.