Common Issues

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

1

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.

2

Fix locally first

Reproduce the error in your local workspace (npm run build or npm run lint). Fix the issue, commit, and push.

3

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.

4

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

CauseDescription
Large data transformMigration script loops over millions of documents; exceeds the timeout window.
Database unreachableNetwork issue or incorrect connection string prevents the migrator from reaching MongoDB.
Lock contentionAnother process holds a write lock on the collection being migrated.

Resolution steps

1

Check migration logs

Look for connection errors or slow query warnings in the publish panel's Migrate stage.

2

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.

3

Verify connection secrets

Ensure MONGO_URL is correctly set in your environment secrets(Preview → Manage → Secrets). See Database (MongoDB) for connection-string format.

4

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 var or 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

1

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

2

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.

3

Test locally

Export the secret in your local shell (export VAR=value) and run the app to confirm it parses correctly.

4

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:

1

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.

2

Fix the error

Address the root cause (add missing secret, correct the listen port, fix the exception). Commit and re-publish.

3

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 OOMKilled or Exit code 137.

Resolution:

1

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.

2

Optimize or paginate

Refactor to stream large responses, paginate queries, or offload processing to a background job.

3

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

1

Switch to webhook mode

Configure your bot to use webhooks instead of polling. Register the webhook URL with the Telegram Bot API:

Bash
curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://yourapp.emergent.host/webhook
2

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

3

Delete any stale webhook

If switching from webhook to polling, clear any existing webhook first:

Bash
curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook
4

Re-publish

Trigger a new published app. The app will initialize correctly with the chosen update method.

5

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 /health or GET /api/health requests, all failing or timing out.

Common causes

CauseDescription
Missing routeNo handler defined for the health-check path.
Database dependencyHealth check queries MongoDB, but DB is unreachable or slow, causing timeouts.
Incorrect listen addressApp binds to 127.0.0.1 instead of 0.0.0.0, making it unreachable from the orchestrator.
Slow startupApp takes longer to initialize than the probe's initial-delay setting.

Resolution steps

1

Implement a lightweight health endpoint

Ensure your app exposes a route that returns 200 OK without heavy logic:

```typescript Express app.get('/health', (req, res) => { res.status(200).json({ status: 'ok' }); }); ```
TypeScript
fastify.get('/health', async () => {
 return { status: 'ok' };
});

Do not query the database or external APIs in the health check - keep it instant.

2

Bind to 0.0.0.0

Verify your server listens on all interfaces:

TypeScript
app.listen(PORT, '0.0.0.0', () => {
 console.log(`Server ready on port ${PORT}`);
});
3

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

4

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.

Was this page helpful?

Related pages