Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(session): name every cause in the init timeout 504

Yudhi Armyndharis000f10430b21
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7545c0ed..6b639c222 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -55,6 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- The dashboard Webhooks Configured card shows a placeholder instead of 0 when the webhook list cannot be read.
- Dashboard message search ignores a response that arrives after a newer query, so stale results no longer replace the current ones.
- A session whose automatic reconnect fails to relaunch the engine (a network, DNS or browser launch error) keeps retrying with backoff instead of stopping in `failed` until restarted by hand; an authentication failure or a stale browser profile still ends in `failed` ([#1580](https://github.com/rmyndharis/OpenWA/issues/1580)).
+- The `504` a start returns when the engine does not finish initializing names every possible cause, an unreachable WhatsApp Web, network or session proxy and a browser stalled during startup, instead of ruling the network out ([#1601](https://github.com/rmyndharis/OpenWA/issues/1601)).
- A session that runs out of reconnect attempts fires the `session:error` plugin hook when it lands in `failed`.
- A session that runs out of reconnect attempts keeps the last attempt's failure reason in `lastError` and in the `session:error` hook, after the attempts message.
- A stop during the retry delay after a transient start failure is no longer undone by the retry; a stop or delete the ownership fence refused leaves the retry alone.
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 3f65fe2cd..042e57eca 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -94,21 +94,21 @@ Validation failures (`statusCode: 400`) return `message` as an **array** of fiel
### General Error Codes
-| HTTP Status | Meaning | When |
-| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `400` | Bad Request | DTO validation failed, unknown body field, or a business precondition not met (e.g. session not active, media over cap) |
-| `401` | Unauthorized | Missing/invalid/expired/revoked `X-API-Key` (or `METRICS_TOKEN` for metrics), a blocked source IP, or a key used outside its `allowedSessions` scope |
-| `403` | Forbidden | A valid, in-scope key whose **role** is below the route's `@RequireRole` requirement |
-| `404` | Not Found | The addressed resource (session, message, webhook, batch, …) does not exist |
-| `409` | Conflict | A uniqueness constraint was violated (e.g. duplicate name); a credential teardown for the same session name is still in flight on `start`/`delete` (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`); or, on routes that reach a WhatsApp engine, the engine exists but is not ready yet (retryable; each route section carries the exact wording); or, on a multi-node deployment, another node currently owns the session's live engine (retryable) |
-| `413` | Payload Too Large | Base64 media exceeds the media byte cap (see §6.3) |
-| `415` | Unsupported Media | The request has a body carrying a `Content-Encoding` other than `identity`; compressed request bodies are not accepted, as the aggregate body cap counts wire bytes |
-| `429` | Too Many Requests | A rate limit was exceeded: the per-client-IP tiers, the ingress per-instance limit, or send pacing (body carries `code: 'SEND_PACING_LIMITED'` and `retryAfterSeconds`); honor `Retry-After` when present |
-| `500` | Internal Server Error | Send failed at the WhatsApp engine or an unexpected server error |
-| `501` | Not Implemented | The operation is not supported by the active engine (see the capability matrix, docs/29) |
-| `502` | Bad Gateway | An engine transport failure (e.g. a dead Baileys socket; retryable), an upstream component returned something unusable (not retryable; each route section carries the exact wording), or, on a multi-node deployment, forwarding a session-scoped request to its owner node failed after the request may already have been sent, so a non-idempotent call must not be replayed blindly (see docs/13) |
-| `503` | Service Unavailable | A dependency or the session is not ready (boot draining, a datastore down, the engine reconnecting); retryable. On a multi-node deployment a forwarded request answers `503` only when the owner node was never reached, so the request was not carried out (see docs/13) |
-| `504` | Gateway Timeout | An upstream the gateway waits on did not answer in time: on a multi-node deployment, the owner node did not answer a forwarded session-scoped request within `SESSION_PROXY_TIMEOUT_MS`; on `POST /sessions/{sessionId}/start` (see §6.4.1), the engine did not finish starting within its timeout, either because the browser wedged mid-startup (often a container memory or resource limit) or because a session pinned to an unreachable `proxyUrl` never connected, and the message names which. On the forwarding path the request may still have been carried out on the owner node, so a non-idempotent call must not be replayed blindly (see docs/13) |
+| HTTP Status | Meaning | When |
+| ----------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | Bad Request | DTO validation failed, unknown body field, or a business precondition not met (e.g. session not active, media over cap) |
+| `401` | Unauthorized | Missing/invalid/expired/revoked `X-API-Key` (or `METRICS_TOKEN` for metrics), a blocked source IP, or a key used outside its `allowedSessions` scope |
+| `403` | Forbidden | A valid, in-scope key whose **role** is below the route's `@RequireRole` requirement |
+| `404` | Not Found | The addressed resource (session, message, webhook, batch, …) does not exist |
+| `409` | Conflict | A uniqueness constraint was violated (e.g. duplicate name); a credential teardown for the same session name is still in flight on `start`/`delete` (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`); or, on routes that reach a WhatsApp engine, the engine exists but is not ready yet (retryable; each route section carries the exact wording); or, on a multi-node deployment, another node currently owns the session's live engine (retryable) |
+| `413` | Payload Too Large | Base64 media exceeds the media byte cap (see §6.3) |
+| `415` | Unsupported Media | The request has a body carrying a `Content-Encoding` other than `identity`; compressed request bodies are not accepted, as the aggregate body cap counts wire bytes |
+| `429` | Too Many Requests | A rate limit was exceeded: the per-client-IP tiers, the ingress per-instance limit, or send pacing (body carries `code: 'SEND_PACING_LIMITED'` and `retryAfterSeconds`); honor `Retry-After` when present |
+| `500` | Internal Server Error | Send failed at the WhatsApp engine or an unexpected server error |
+| `501` | Not Implemented | The operation is not supported by the active engine (see the capability matrix, docs/29) |
+| `502` | Bad Gateway | An engine transport failure (e.g. a dead Baileys socket; retryable), an upstream component returned something unusable (not retryable; each route section carries the exact wording), or, on a multi-node deployment, forwarding a session-scoped request to its owner node failed after the request may already have been sent, so a non-idempotent call must not be replayed blindly (see docs/13) |
+| `503` | Service Unavailable | A dependency or the session is not ready (boot draining, a datastore down, the engine reconnecting); retryable. On a multi-node deployment a forwarded request answers `503` only when the owner node was never reached, so the request was not carried out (see docs/13) |
+| `504` | Gateway Timeout | An upstream the gateway waits on did not answer in time: on a multi-node deployment, the owner node did not answer a forwarded session-scoped request within `SESSION_PROXY_TIMEOUT_MS`; on `POST /sessions/{sessionId}/start` (see §6.4.1), the engine did not finish starting within its timeout, either because initialization never finished at all (WhatsApp Web, the network or the session `proxyUrl` unreachable in a way that hangs the connection, or a browser stalled mid-startup, for example under a container memory or resource limit) or because the engine's own auth poll expired after the page loaded (typically an unreachable `proxyUrl`), and the message names which. On the forwarding path the request may still have been carried out on the owner node, so a non-idempotent call must not be replayed blindly (see docs/13) |
### Timestamp Conventions
@@ -616,7 +616,7 @@ No request body.
Returned via `transformSession`. Status typically transitions to `initializing` / `qr_ready`.
-**Errors:** `400` session already started / already starting · `401` · `403` · `404` not found · `409` credential teardown for the same session name still in flight (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; no destructive side effect runs before the refusal — a retry after cleanup settles proceeds) · `504` the engine did not finish starting within its timeout (wedged browser, resource limit, or an unreachable `proxyUrl`); the engine is torn down, so the start can be retried once the cause is addressed
+**Errors:** `400` session already started / already starting · `401` · `403` · `404` not found · `409` credential teardown for the same session name still in flight (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; no destructive side effect runs before the refusal — a retry after cleanup settles proceeds) · `504` the engine did not finish starting within its timeout (WhatsApp Web or the network unreachable, a stalled browser or resource limit, or an unreachable `proxyUrl`); the engine is torn down, so the start can be retried once the cause is addressed
#### POST /api/sessions/:sessionId/stop
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 5c462dcfc..38694029b 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -276,6 +276,14 @@ curl -X POST "$BASE/api/sessions" -H "X-API-Key: $API_KEY" -H "Content-Type: app
> ℹ️ Proxy egress for the `whatsapp-web.js` engine is configured **per session** via the
> `proxyUrl`/`proxyType` fields on `POST /api/sessions` — not via environment variables.
+> ℹ️ A `504` whose body starts with `Engine initialization timed out after ...` is a **different**
+> failure with a different fix: initialization never finished at all. That happens when WhatsApp Web,
+> the network or the session proxy is unreachable in a way that hangs the connection instead of
+> failing it, and when the browser stalls during startup (typically a container memory or resource
+> limit). Check egress to `web.whatsapp.com`, the session's `proxyUrl` and the container's memory
+> limit. The auth poll that produces the message above only starts once the page has loaded, so it
+> never fires for a connection that hangs before that.
+
### Issue: Session stuck at `authenticating`, never reaches `ready`
> **Engine:** This stall applies to the `whatsapp-web.js` engine only. Baileys also reports `authenticating`, but only for the seconds between WhatsApp accepting the link and the restart it requests; it cannot park there, so if you are using `ENGINE_TYPE=baileys`, skip this section.
diff --git a/docs/31-session-lifecycle-design.md b/docs/31-session-lifecycle-design.md
index 7bd864a94..c31f9e97a 100644
--- a/docs/31-session-lifecycle-design.md
+++ b/docs/31-session-lifecycle-design.md
@@ -54,14 +54,16 @@ is the single most repeated invariant in the module.
### INV-4 — Init timeout evicts and 504s; init rejection propagates as FAILED
**Interleaving:** whatsapp-web.js calls `page.goto(..., {timeout: 0})` — a hung browser never
-rejects, so a plain `await` hangs the start forever.
+rejects, and neither does a navigation that never completes because WhatsApp Web is unreachable, so
+a plain `await` hangs the start forever. The engine's own `authTimeoutMs` poll does not cover that
+case: whatsapp-web.js only starts it in `inject()`, after the page has loaded.
**Defense:** `Promise.race` deadline in `initializeEngine`; on timeout the engine is evicted +
force-destroyed + status DISCONNECTED + 504 to the caller. A REAL rejection is NOT treated as a
timeout: it propagates so `start()` records FAILED with the reason.
**Pinned by:** `session.service.spec.ts` (start failure-path cases; the timeout/rejection
split lives in `session.service.spec.ts`'s init-timeout describes).
**Do not "simplify" the two paths into one** — the distinction is why a bad proxy config returns
-FAILED + reason while a wedged browser returns 504 + eviction.
+FAILED + reason while an init that never completes returns 504 + eviction.
### INV-5 — Delete racing a start re-purges auth directories after init resolves
diff --git a/src/modules/session/session-engine-lifecycle.service.ts b/src/modules/session/session-engine-lifecycle.service.ts
index 9f33cc99f..ee8c48ae6 100644
--- a/src/modules/session/session-engine-lifecycle.service.ts
+++ b/src/modules/session/session-engine-lifecycle.service.ts
@@ -636,8 +636,9 @@ export class SessionEngineLifecycle {
// engine.initialize() launches Chromium and navigates to WhatsApp Web with no internal timeout:
// whatsapp-web.js calls page.goto(..., { timeout: 0 }) and its web-version-cache fetch has none
// either. If the browser stalls under container memory pressure (observed in prod: a session
- // wedged in INITIALIZING with no error logged and GET /sessions/:id/qr 400ing forever), this
- // await never settles. Race it against a deadline so a wedged init fails fast instead.
+ // wedged in INITIALIZING with no error logged and GET /sessions/:id/qr 400ing forever), or if
+ // WhatsApp Web is simply unreachable so the navigation never completes, this await never settles.
+ // Race it against a deadline so a wedged init fails fast instead.
//
// ONLY the timeout case mutates state here. A REAL rejection (e.g. Chromium can't launch) must
// propagate untouched so start()'s catch keeps owning FAILED+reason (the diagnosability #600/#631
@@ -681,12 +682,18 @@ export class SessionEngineLifecycle {
await this.teardownEngineSafely(id, engine, e => e.forceDestroy(), 'force-destroy');
await this.updateStatus(id, SessionStatus.DISCONNECTED);
// Map to a diagnostic 504 like the auth-timeout branch below, so a wedged init doesn't escape as a
- // bare 500 (#733 follow-up). The browser stalled mid-startup — usually a container memory/resource
- // limit or a wedged Chromium, not a network/proxy issue (that's the auth-timeout's signature).
+ // bare 500 (#733 follow-up). This deadline covers EVERY cause and cannot tell them apart: the
+ // auth-timeout below only fires once the page has LOADED (whatsapp-web.js navigates with
+ // page.goto(..., { waitUntil: 'load', timeout: 0 }) and starts its authTimeoutMs poll in inject()
+ // afterwards), so a navigation that hangs (an unreachable WhatsApp Web, or a proxy that accepts
+ // the connection and never answers) hits this deadline too, not the auth timeout. The message must
+ // name every cause and rule out none. It also says ENGINE, not browser: the deadline is
+ // engine-agnostic (Baileys launches no browser), and in the hang case the browser did start.
throw new HttpException(
- `Engine initialization timed out after ${err.timeoutMs}ms — the browser process did not complete ` +
- 'startup in time (often a container memory/resource limit or a stalled Chromium, not a network ' +
- 'issue). Retry the session; for chronically slow first boots, raise WWEBJS_AUTH_TIMEOUT_MS.',
+ `Engine initialization timed out after ${err.timeoutMs}ms: the engine did not finish starting. ` +
+ 'WhatsApp Web, the network or the session proxy may be unreachable, or the browser may have ' +
+ 'stalled during startup (for example a container memory/resource limit). Retry the session; for ' +
+ 'chronically slow first boots, raise WWEBJS_AUTH_TIMEOUT_MS.',
HttpStatus.GATEWAY_TIMEOUT,
);
} else if (isAuthTimeoutRejection(err)) {
diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.ts
index 95fa3c7a8..0caca2b76 100644
--- a/src/modules/session/session.service.spec.ts
+++ b/src/modules/session/session.service.spec.ts
@@ -1818,7 +1818,19 @@ describe('SessionService', () => {
// runs inside initializeEngine before the mapped error is thrown — asserted below.
expect(caught).toBeInstanceOf(HttpException);
expect((caught as HttpException).getStatus()).toBe(HttpStatus.GATEWAY_TIMEOUT);
- expect((caught as HttpException).getResponse() as string).toMatch(/timed out after 60000ms/i);
+ const body = (caught as HttpException).getResponse() as string;
+ expect(body).toMatch(/timed out after 60000ms/i);
+ // This deadline cannot tell an unreachable WhatsApp Web or session proxy from a stalled browser:
+ // whatsapp-web.js navigates with { waitUntil: 'load', timeout: 0 } and only starts its auth poll
+ // after the page has loaded, so a navigation that hangs fires this timeout, not the auth one. The
+ // diagnostic must name every cause and rule out none, or it points the operator away from the
+ // network. It must also blame the ENGINE, not the browser: the deadline is engine-agnostic, and a
+ // hung navigation means the browser started fine.
+ expect(body).toMatch(/the engine did not finish starting/i);
+ expect(body).not.toMatch(/browser did not finish starting/i);
+ expect(body).toMatch(/WhatsApp Web, the network or the session proxy may be unreachable/i);
+ expect(body).toMatch(/may have stalled during startup/i);
+ expect(body).not.toMatch(/not a network/i);
expect(mockEngine.forceDestroy).toHaveBeenCalled(); // wedged browser reaped
expect(intern().engines.has('sess-uuid-1')).toBe(false); // slot freed for retry
expect(repository.update).toHaveBeenCalledWith('sess-uuid-1', { status: SessionStatus.DISCONNECTED });