Publishing issues

Overview

Publishing issues fall into two broad categories: build-time failures (the agent cannot bundle or prepare your app) and runtime failures (your app starts but behaves incorrectly or crashes). This page walks through the most common scenarios and how to resolve them.

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.

Check the publishing pipeline first

Most build errors appear in the publishing pipeline log. See Publishing pipeline failures for step-by-step diagnostics.

Build-time failures

Missing dependencies

Symptom: Build fails with

Module not found

Cannot find package

Cause: The agent has not added a required library to

package.json

(Node.js),

requirements.txt

(Python), or your framework's manifest.

Fix:

Identify the missing package

Read the build log; the error message names the import that failed.

Tell the agent in chat

"Install

[package-name]

and re‑publish." The agent will add the dependency and trigger a new build.

Verify the manifest

In the Files pane, confirm the package appears in

package.json

requirements.txt

before the next published app.

Incompatible Node / Python version

Symptom: Build fails with syntax errors or a message like

Unexpected token

(Node) or

invalid syntax

(Python).

Cause: The published app runtime uses a different language version than the code expects (for example, async/await syntax in Node 12, or Python 3.11 match statements on a Python 3.9 runtime).

Fix:

Check the Publishing types page for the runtime version your plan provides.
Ask the agent: "Use syntax compatible with Node 16" (or the version you have).
Re‑generate the code and re‑publish.

Info

If you need a specific runtime version, consider upgrading your Publishing plan level or switching to a Docker‑based published app (if available on your plan).

Build timeout

Symptom: Build aborts with

Timeout exceeded

Build killed

Cause: The build step (install dependencies, transpile, bundle) runs longer than the time limit for your plan.

Fix:

Ask the agent to remove unused libraries or combine smaller packages. Fewer dependencies = faster install.

For Next.js or Vite apps, disable source maps in production or switch to a lighter bundler mode. Example: "Set

productionBrowserSourceMaps: false

in
next.config.js
."

Out of memory during build

Symptom: Build crashes with

JavaScript heap out of memory

Killed

Cause: The build process (Webpack, Vite, TypeScript compiler) exceeds available RAM.

Fix:

Node apps: Add
```
NODE_OPTIONS=--max-old-space-size=4096
```
to your build environment (ask the agent to set this in the publish config).
Simplify the build: Split large bundles, enable tree‑shaking, or lazy‑load heavy modules.
Upgrade plan: More RAM is available at higher tiers - see Publishing plan levels.

Runtime failures

App starts but shows a blank page

Symptom: Published app succeeds; opening the URL displays a white screen or "Application error."

Common causes & fixes:

Cause	How to diagnose	Fix
Client‑side crash	Open browser DevTools → Console; look for uncaught exceptions.	Share the error with the agent: "Fix runtime error: [paste stack trace]."
Missing environment variable	App tries to read `process.env.API_KEY` but it's undefined.	Set the variable in the Secrets tab and re‑publish. See How apps work here.
Static‑asset 404	CSS or JS files return 404; check Network tab in DevTools.	Ask the agent to fix the public path or output directory in the build config.

Database connection failures

Symptom: Logs show

MongoNetworkError

ECONNREFUSED

, or similar.

Cause: The app cannot reach the MongoDB instance - wrong connection string, firewall rule, or the database is not provisioned.

Fix:

Verify the database is provisioned

Confirm your app has a MongoDB database - check in the Database panel in the Manage Publishing panel( click Re-publish to open) or ask the agent: "Does this app have a database?" If not, ask: "Add a MongoDB database to this project."

Check the connection string

The environment variable (

MONGO_URL

DB_NAME

) must match the value shown in the Secrets tab (under Preview → Manage → Secrets). Copy it exactly - include username, password, and database name.

Whitelist the published app IP

Emergent publishes from fixed egress IPs. If your MongoDB host has an IP allowlist, retrieve the current IP list from app.emergent.sh/ip-addresses and add those addresses.

Credentials in code

Never hard‑code

mongodb://user:pass@host

in your source files. Always use environment variables and keep secrets out of version control.

API or external service timeouts

Symptom: Requests to third‑party APIs (Stripe, OpenAI, etc.) hang or return

504 Gateway Timeout

Possible causes:

Rate limit: Your API key has hit a quota.
Network policy: The publish environment blocks outbound HTTPS to certain domains (rare).
Slow endpoint: The third‑party service is down or experiencing latency.

Fix:

Check the third‑party status page (e.g.,
```
status.openai.com
```
).
Increase timeout in your HTTP client (Axios, Fetch): set
```
timeout: 30000
```
(30 seconds).
Verify API key: Confirm the key is valid and has sufficient quota; test it locally or in a tool like Postman.
Review logs: Look for
```
429 Too Many Requests
```
or
```
401 Unauthorized
```
- these point to credential or quota issues, not network problems.

Published app health check fails

Symptom: Publishing pipeline succeeds, but the platform marks the app as unhealthy and does not route traffic.

Cause: The health‑check endpoint (

/health

) does not return the required status within the timeout window. The platform checks for an HTTP 200 response on the frontend and a response with status < 500 on the backend at

/health

, with a fixed 10-second timeout and 3 retries (20-second interval).

Fix:

Add or fix the health route: Ensure your app responds to
```
GET /health
```
with a 200 status (frontend) or any status below 500 (backend), with minimal logic (e.g.,
```
res.json({ status: 'ok' })
```
).
Speed up startup: Move heavy initialization (database seeding, large file reads) out of the main server bootstrap so the health check can succeed quickly.

Custom domain not resolving

Symptom: Visiting

app.yourdomain.com

shows a DNS error or "Site not found."

Diagnosis:

Verify DNS records

Run

dig yourdomain.com

or use an online DNS checker. For the root domain, you must have two A records pointing to 162.159.142.117 and 172.66.2.113. For

www

, add a CNAME pointing to your production hostname. Do not use a CNAME for the root domain, and never point records to a preview URL.

Wait for propagation

DNS changes can take 1-48 hours to propagate globally. Test from multiple locations or use

8.8.8.8

as your resolver.

Check SSL certificate status

In the workspace, navigate to Preview → Manage → Domain → Check Status** and confirm the SSL certificate shows Active-Verified. If it shows Pending, wait a few more minutes; if Failed, double‑check your DNS records.

Info

Detailed setup instructions: Custom domain.

Out of credits / quota exceeded

Symptom: Published app is rejected with

INSUFFICIENT_CREDITS

, or aborts with "Insufficient credits." Note that live apps can still re-publish at a low balance; new published versions require a minimum credit threshold.

Cause: Your account has consumed its credit allocation for builds, compute time, or API calls.

Fix:

Check your balance: Open the Billing or Usage dashboard (depending on your plan).
Upgrade or top up: Purchase additional credits or move to a higher plan tier with more monthly allowance.
Optimize usage: Reduce the number of published versions by batching changes; use preview builds sparingly.

Image / video / audio generation failures

Symptom: AI‑generated media assets fail to appear or return errors.

Cause: Model unavailable, quota exceeded, or unsupported parameters.

Fix: See the dedicated page AI media generation for model‑specific troubleshooting and parameter guidance.

Getting further help

If none of the above resolves your issue:

Ask the agent

Paste the full error message into chat. The agent can read logs and often auto‑fix configuration mistakes.

Check platform status

Rare outages or maintenance windows are announced on the Emergent status page (link in your workspace footer).

Contact support

Use the Help button in the workspace to open a ticket. Include your project ID and the timestamp of the failed published app.

Most issues resolve in chat

The agent has access to your publish logs and can iterate on fixes in real time - start there before opening a support ticket.

Publishing issues

Overview

Build-time failures

Missing dependencies

Identify the missing package

Tell the agent in chat

Verify the manifest

Incompatible Node / Python version

Build timeout

Out of memory during build

Runtime failures

App starts but shows a blank page

Database connection failures

Verify the database is provisioned

Check the connection string

Whitelist the published app IP

API or external service timeouts

Published app health check fails

Custom domain not resolving

Verify DNS records

Wait for propagation

Check SSL certificate status

Out of credits / quota exceeded

Image / video / audio generation failures

Getting further help

Ask the agent

Review the pipeline log

Check platform status

Contact support

Great! What worked best for you?

Related pages