Publishing pipeline failures
Overview
Publishing failures in Emergent typically fall into one of six categories: build-time errors, database migration timeouts, environment-secret issues, container crashes, webhook conflicts, and failed health checks. This page walks through each failure mode, its symptoms, and how to resolve it.
Coming from another platform? Publishing is the same thing as deploying - what other tools call deploy, deployment, or redeploy, Emergent calls Publish and Re-publish.
Publish logs are your friend
The published app panel shows real-time logs for each stage - build, migrate, publish. When a published app fails, scroll to the error message and look for the stack trace or last successful step.
Build errors
Build failures occur during the TypeScript compile, linting, or dependency-resolution phase. Emergent runs npm install (or the equivalent for your package manager) then compiles your code; any error here halts the pipeline before containers are started.
Common causes
- TypeScript errors - Type mismatches, missing imports, or incorrect generics introduced by a recent code generation.
- ESLint violations - The build enforces your project's linting rules; a new unused variable or disallowed pattern will block published app.
- Dependency conflicts - Incompatible package versions, missing peer dependencies, or a corrupted
package-lock.json.
Resolution steps
Read the build log
Open the published app panel and expand the Build stage. The last few lines will show the exact file and line number.
Fix locally first
Reproduce the error in your local workspace (npm run build or npm run lint). Fix the issue, commit, and push.
Dependency conflicts
If the error mentions peer-dependency warnings or version mismatches, run npm install locally to regenerate lock files, then commit the updated package-lock.json.
Retry the published app
Once you've pushed the fix, trigger a new publish from the workspace or let the automatic published app pick up the latest commit.
Auto-generated code
If the agents introduced the error during a recent generation, describe the issue in chat (e.g. "Build is failing with TS error on line 42 of api/users.ts") and the agent will propose a corrective change.
Database migration timeouts
When your app includes schema changes (new collections, indexes, or data transforms), Emergent runs a migration step, on the first publish and during Replace operations, this performs a data dump/restore from preview to the production Atlas instance, before starting the new containers. If the migration script takes too long or cannot connect to MongoDB, the publish will time out.
Symptoms
- Publish logs show
Running migrations…for several minutes, then fail with a timeout or connection error. - No new containers are started; the previous version continues to run.
Common causes
| Cause | Description |
|---|---|
| Large data transform | Migration script loops over millions of documents; exceeds the timeout window. |
| Database unreachable | Network issue or incorrect connection string prevents the migrator from reaching MongoDB. |
| Lock contention | Another process holds a write lock on the collection being migrated. |
Resolution steps
Check migration logs
Look for connection errors or slow query warnings in the publish panel's Migrate stage.
Optimize the migration
If the script is slow, refactor it to batch updates or use bulk operations. Ask the agent to rewrite the migration for better performance.
Verify connection secrets
Ensure MONGO_URL is correctly set in your environment secrets(Preview → Manage → Secrets). See Database (MongoDB) for connection-string format.
Increase timeout (if available)
Contact support if your migration legitimately requires more than the default window; the Emergent team can adjust the timeout for your workspace.
Info
If the migration is a one-time backfill, consider running it manually via a script in your workspace, then removing the migration step and publishing again.
Secret-export issues
Published versions can fail if required environment variables are missing, malformed, or contain invalid characters that break the container's shell environment.
Symptoms
- Publish succeeds but the app immediately crashes with
Missing required env varor similar. - Logs show escaped characters or truncated secret values.
Common causes
- A new feature expects an API key (e.g.
STRIPE_SECRET_KEY) that hasn't been added to the workspace secrets. - Secret value contains unescaped quotes, newlines, or special shell characters.
- Copy-paste error introduced invisible characters or trailing whitespace.
Resolution steps
Audit required secrets
Check your code for process.env.VARIABLE_NAME references and ensure each is defined in the workspace's Secrets panel(Preview → Manage → Secrets).
Re-enter the secret
Note that keys cannot be deleted from the Secrets panel(Preview → Manage → Secrets), to correct a secret, edit the value of the existing key in the UI to eliminate hidden characters. Paste the value directly from the provider (no intermediate text editor). To add a new key, ask the agent to add it to .env, then re-publish.
Test locally
Export the secret in your local shell (export VAR=value) and run the app to confirm it parses correctly.
Re-publish
Once all secrets are present and valid, trigger a new published app. The containers will pick up the updated environment.
Universal LLM Key
If your app uses AI features, remember to set The Universal LLM Key in secrets(Preview → Manage → Secrets) - many AI generation failures stem from a missing or expired key.
CrashLoopBackOff and OOM kills
After a successful build, containers may crash repeatedly (CrashLoopBackOff) or be killed by the orchestrator for exceeding memory limits (OOM kill). Both prevent the published app from reaching a healthy state.
CrashLoopBackOff
The container starts but exits within seconds, triggering an automatic restart loop.
Common causes:
- Uncaught exception during startup (missing secret, database connection failure).
- Port mismatch - app listens on a port different from the one the health check expects.
- Syntax error or runtime crash in initialization code.
Resolution:
Read container logs
The publish panel's Runtime tab shows stdout/stderr from the crashed container. Look for the stack trace or last log line before the crash.
Fix the error
Address the root cause (add missing secret, correct the listen port, fix the exception). Commit and re-publish.
Verify health-check endpoint
Ensure your app exposes the health-check route (/health or /api/health) and it returns 200 OK when the app is ready.
OOM kills
The container is terminated because it consumed more memory than allocated.
Symptoms:
- Logs end abruptly with no stack trace.
- Publish panel shows
OOMKilledorExit code 137.
Resolution:
Identify memory-hungry code
Profile the app locally or add logging to track memory usage. Common culprits: large in-memory caches, file uploads held in RAM, unbounded data fetches.
Optimize or paginate
Refactor to stream large responses, paginate queries, or offload processing to a background job.
Request a memory increase
If the app legitimately needs more RAM, contact support to raise the container's memory limit for your workspace.
Mobile WebView apps
Apps converted from web to mobile via Web to Mobile conversion may bundle larger assets; ensure image/video assets are optimized or served from CDN rather than embedded.
Telegram 409 conflicts
If your app integrates a Telegram bot, published versions may encounter a 409 Conflict error. This happens when more than one instance of your bot is running in polling mode simultaneously, causing conflicts over who receives updates.
Cause
Telegram does not allow more than one instance to poll for updates with the same bot token at a time. If you run multiple instances (e.g. staging + production) using the same token in polling mode, Telegram rejects the duplicate poller. The fix is to switch to webhook mode or ensure only a single instance is polling.
Resolution
Switch to webhook mode
Configure your bot to use webhooks instead of polling. Register the webhook URL with the Telegram Bot API:
curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://yourapp.emergent.host/webhookOr ensure a single poller
If you prefer polling, ensure only one instance of the bot is running at a time. Stop any duplicate instances (e.g. staging environments using the same token) before publishing.
Delete any stale webhook
If switching from webhook to polling, clear any existing webhook first:
curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhookRe-publish
Trigger a new published app. The app will initialize correctly with the chosen update method.
Use separate bot tokens per environment
Avoid sharing a bot token between environments. Use separate bot tokens for staging and production to prevent conflicts regardless of update method.
Info
If you recently changed your custom domain, the old webhook URL may still be registered. Deleting it resolves the conflict.
Health-check failures
Emergent waits for your app to respond successfully to health-check probes before marking the published app as live. If the checks time out or return non-2xx status codes, the published app is marked as failed; the previously live version continues running (no rollback event is triggered, and an auto failure-recovery agent will attempt to resolve the issue).
Symptoms
- Publish progresses past build and migrate, then stalls at Starting containers…
- Logs show repeated
GET /healthorGET /api/healthrequests, all failing or timing out.
Common causes
| Cause | Description |
|---|---|
| Missing route | No handler defined for the health-check path. |
| Database dependency | Health check queries MongoDB, but DB is unreachable or slow, causing timeouts. |
| Incorrect listen address | App binds to 127.0.0.1 instead of 0.0.0.0, making it unreachable from the orchestrator. |
| Slow startup | App takes longer to initialize than the probe's initial-delay setting. |
Resolution steps
Implement a lightweight health endpoint
Ensure your app exposes a route that returns 200 OK without heavy logic:
fastify.get('/health', async () => {
return { status: 'ok' };
});Do not query the database or external APIs in the health check - keep it instant.
Bind to 0.0.0.0
Verify your server listens on all interfaces:
app.listen(PORT, '0.0.0.0', () => {
console.log(`Server ready on port ${PORT}`);
});Check readiness logic
If your app must wait for DB or cache to initialize, expose a separate /ready endpoint and ensure the health check uses /health (which always returns 200).
Review probe timing
Contact support if your app's startup genuinely requires more time than the default initial delay; the team can adjust probe settings for your workspace.
Fast health checks = faster rollouts
A quick, dependency-free health endpoint ensures published versions complete in seconds and the previously live version stays up if something goes wrong.

