Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(engine): answer 409 when a page reload cuts a wwebjs call

Yudhi Armyndharisa4b1ee49c1aa
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1dfe525e2..7ed5f8adb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -70,6 +70,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Preserve literal request values in custom ingress acknowledgments.
- Honor inclusive millisecond lower bounds in built-in search.
- Preserve replacement plugin search providers during worker recovery.
+- Answer 409 instead of a bare 500 when WhatsApp Web reloads its page under a running whatsapp-web.js read, and no longer report a group, contact, label or invite lookup cut short that way as not found (404); accepting an invite answers 503 because the join may have landed.
- Answer 409 naming the path and the cause on `GET /api/infra/storage/files/count` and `/export` when the local storage directory holds a symbolic link, a directory the app cannot read or one nested 20 levels deep, instead of silently leaving those files out of the count and the archive.
- Normalize CRLF line endings in SDK contract parsers so Windows checkouts do not produce false contract mismatches (#1885). Thanks @Purushotham-Prajapati-24.
- Exclude local repository metadata from Java SDK Maven Central bundles built with Maven 3.10 (#1879).
diff --git a/src/engine/adapters/whatsapp-web-js.adapter.ts b/src/engine/adapters/whatsapp-web-js.adapter.ts
index 2bb8bc2c5..580761369 100644
--- a/src/engine/adapters/whatsapp-web-js.adapter.ts
+++ b/src/engine/adapters/whatsapp-web-js.adapter.ts
@@ -59,7 +59,7 @@ import { WwebjsChats } from './wwebjs-chats';
import { WwebjsCatalog } from './wwebjs-catalog';
import { registerWwebjsGroupEvents } from './wwebjs-group-events';
import { WwebjsOnboardingWatcher } from './wwebjs-onboarding';
-import { WwebjsLifecycle } from './wwebjs-lifecycle';
+import { PAGE_RELOADING_MESSAGE, WwebjsLifecycle } from './wwebjs-lifecycle';
import { WwebjsReadyReconcile } from './wwebjs-reconcile';
import { WwebjsStuckAuth } from './wwebjs-stuck-auth';
import { WwebjsCalls } from './wwebjs-calls';
@@ -962,9 +962,7 @@ export class WhatsAppWebJsAdapter implements IWhatsAppEngine {
// breaker for its 15-minute cooldown). Answer the same retryable 409 the pre-READY states get,
// naming the reload so the operator can tell this state from a plain disconnect (#1081).
if (this.lifecycle.isInNavigationReinjectWindow()) {
- throw new EngineNotReadyError(
- 'WhatsApp Web is reloading its page and the session is re-injecting. Retry in a few seconds.',
- );
+ throw new EngineNotReadyError(PAGE_RELOADING_MESSAGE);
}
}
diff --git a/src/engine/adapters/wwebjs-chats.ts b/src/engine/adapters/wwebjs-chats.ts
index 4fdaec38f..520c3532e 100644
--- a/src/engine/adapters/wwebjs-chats.ts
+++ b/src/engine/adapters/wwebjs-chats.ts
@@ -5,7 +5,7 @@ import { ChatSummary, ChatState } from '../interfaces/whatsapp-engine.interface'
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { chatKind, isChannelJid } from '../identity/wa-id';
import { WwebjsMessaging } from './wwebjs-messaging';
-import { type WwebjsEngineHost } from './wwebjs-host';
+import { type WwebjsEngineHost, rethrowIfNavigation } from './wwebjs-host';
import { isProtocolTimeout } from './wwebjs-lifecycle';
import { mapWwebjsMessageType } from './message-mapper';
@@ -58,6 +58,7 @@ function rethrowTransportFailure(
activity: string,
timedOutMessage = `WhatsApp Web did not answer in time while ${activity}`,
): void {
+ rethrowIfNavigation(host, error);
if (host.isPageTransportError(error)) {
host.reportIfPageTransportError(error, context);
throw new EngineTransportError(`Transport died while ${activity}`);
@@ -253,6 +254,7 @@ export class WwebjsChats {
try {
return await op();
} catch (error) {
+ rethrowIfNavigation(this.host, error);
if (this.host.isPageTransportError(error)) {
this.host.reportIfPageTransportError(error, context);
throw new EngineTransportError(`Transport died during ${context}`);
diff --git a/src/engine/adapters/wwebjs-contacts.ts b/src/engine/adapters/wwebjs-contacts.ts
index 8fa3523bf..430a63b09 100644
--- a/src/engine/adapters/wwebjs-contacts.ts
+++ b/src/engine/adapters/wwebjs-contacts.ts
@@ -5,7 +5,7 @@ import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error'
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { parseWaId, userPart } from '../identity/wa-id';
import { readWid, type SerializedWid } from '../types/whatsapp-web-js.types';
-import { type WwebjsEngineHost, withPage } from './wwebjs-host';
+import { type WwebjsEngineHost, rethrowIfNavigation, withPage } from './wwebjs-host';
import { isProtocolTimeout } from './wwebjs-lifecycle';
/** The raw whatsapp-web.js contact element type, kept local so the wwebjs `Contact` type never leaks. */
@@ -181,6 +181,7 @@ export class WwebjsContacts {
unreadable = read?.failed ?? 0;
firstError = read?.firstError;
} catch (error) {
+ rethrowIfNavigation(this.host, error);
// A dead page surfaces here as a raw Puppeteer error; convert it to the documented transport
// failure the way wwebjs-chats.ts does, so a transport death answers 503 instead of a bare 500.
if (this.host.isPageTransportError(error)) {
@@ -237,6 +238,7 @@ export class WwebjsContacts {
const contact = await this.client().getContactById(contactId);
return this.toContact(contact);
} catch (error) {
+ rethrowIfNavigation(this.host, error);
// Unlike the avatar lookup, a throw here can legitimately mean the contact is absent:
// `window.WWebJS.getContact` has no try/catch and reads `contact.isBusiness` straight off
// `Contact.find`, so an unknown id throws a TypeError on null. Null (→ 404) stays the answer
@@ -370,6 +372,7 @@ export class WwebjsContacts {
try {
url = await this.client().getProfilePicUrl(contactId);
} catch (error) {
+ rethrowIfNavigation(this.host, error);
const pageDown = this.host.isPageTransportError(error) || isProtocolTimeout(error);
const viaLid = byLid && !pageDown ? await this.profilePictureByLid(contactId) : undefined;
if (viaLid) return viaLid;
diff --git a/src/engine/adapters/wwebjs-groups.ts b/src/engine/adapters/wwebjs-groups.ts
index 857cf0dab..c2b82792b 100644
--- a/src/engine/adapters/wwebjs-groups.ts
+++ b/src/engine/adapters/wwebjs-groups.ts
@@ -19,8 +19,8 @@ import { EngineNotSupportedError } from '../../common/errors/engine-not-supporte
import { GroupNotFoundError } from '../../common/errors/group-not-found.error';
import { InvalidInviteCodeError } from '../../common/errors/invalid-invite-code.error';
import { toMessageMedia } from './wwebjs-messaging';
-import { type WwebjsEngineHost, withPage, reportPageDeath } from './wwebjs-host';
-import { isProtocolTimeout } from './wwebjs-lifecycle';
+import { type WwebjsEngineHost, rethrowIfNavigation, withPage, reportPageDeath } from './wwebjs-host';
+import { isNavigationError, isProtocolTimeout } from './wwebjs-lifecycle';
import { listChats } from './wwebjs-chats';
/**
@@ -188,6 +188,7 @@ export class WwebjsGroups {
// A dead page and a genuinely-missing group both land in this catch; only the second may
// become null (→ service 404). A transport death surfaced as "group not found" sends
// operators debugging the wrong layer — report it and answer 503 instead.
+ rethrowIfNavigation(this.host, error);
if (this.host.isPageTransportError(error)) {
this.host.reportIfPageTransportError(error, 'getGroupInfo');
throw new EngineTransportError(`Transport died while reading group ${groupId}`);
@@ -434,6 +435,7 @@ export class WwebjsGroups {
} catch (error) {
// A dead page and a refused invite both land here; only the second is a 404. Folding a
// transport death into "no such invite" sends operators debugging the wrong layer.
+ rethrowIfNavigation(this.host, error);
if (this.host.isPageTransportError(error)) {
this.host.reportIfPageTransportError(error, 'getGroupJoinInfo');
throw new EngineTransportError(`Transport died while previewing invite ${inviteCode}`);
@@ -490,6 +492,10 @@ export class WwebjsGroups {
if (isProtocolTimeout(error)) {
throw new EngineTransportError('WhatsApp Web did not answer the group invite acceptance in time');
}
+ // A reload cut the call: the same unknown outcome, and not a refused invite either.
+ if (isNavigationError(error)) {
+ throw new EngineTransportError('WhatsApp Web reloaded its page during the group invite acceptance');
+ }
this.host.logger.warn(`Failed to accept group invite: ${String(error)}`);
groupId = undefined;
}
diff --git a/src/engine/adapters/wwebjs-host.ts b/src/engine/adapters/wwebjs-host.ts
index 73a460816..d96cea7a1 100644
--- a/src/engine/adapters/wwebjs-host.ts
+++ b/src/engine/adapters/wwebjs-host.ts
@@ -8,7 +8,7 @@ import { type createLogger } from '../../common/services/logger.service';
import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { type WhatsAppWebJsConfig } from './whatsapp-web-js.adapter';
-import { toCapturedPageError } from './wwebjs-lifecycle';
+import { PAGE_RELOADING_MESSAGE, isNavigationError, toCapturedPageError } from './wwebjs-lifecycle';
/**
* Shared host surface for the delegates extracted from WhatsAppWebJsAdapter (./wwebjs-groups,
@@ -54,10 +54,24 @@ export function requireClient(host: WwebjsEngineHost): Client {
return client;
}
+/**
+ * Answer the retryable 409 the adapter gives inside the navigation window when the error says the page
+ * navigated under the call, and return for any other error. A call already in flight when WhatsApp Web
+ * reloads dies with Puppeteer's navigation error before the window is stamped, so it would otherwise be a
+ * bare 500, or, where a catch folds a failed lookup into "not found", a 404 for a group, contact or label
+ * that exists. A navigation is not a death: nothing is reported.
+ */
+export function rethrowIfNavigation(host: WwebjsEngineHost, error: unknown): void {
+ // A page the host already reads as dead is reported as dead, whatever the message says.
+ if (isNavigationError(error) && !host.isPageTransportError(error))
+ throw new EngineNotReadyError(PAGE_RELOADING_MESSAGE);
+}
+
/**
* Run a client operation, classifying a dead page/transport as the documented 503 plus an early
* death signal instead of an opaque 500 under a status that still says READY - the split every
- * chats read already makes (#1081). Other errors propagate unchanged.
+ * chats read already makes (#1081), and a page that navigated under the call as the 409 of
+ * {@link rethrowIfNavigation}. Other errors propagate unchanged.
*
* Lives here rather than per delegate: ./wwebjs-channels, ./wwebjs-profile and ./wwebjs-status each
* held a byte-identical private copy, and ./wwebjs-contacts needed a fourth.
@@ -66,6 +80,7 @@ export async function withPage<T>(host: WwebjsEngineHost, context: string, op: (
try {
return await op();
} catch (error) {
+ rethrowIfNavigation(host, error);
if (host.isPageTransportError(error)) {
host.reportIfPageTransportError(error, context);
throw new EngineTransportError(`Transport died during ${context}`);
diff --git a/src/engine/adapters/wwebjs-labels.ts b/src/engine/adapters/wwebjs-labels.ts
index 9d5ef69b2..28e9e83d9 100644
--- a/src/engine/adapters/wwebjs-labels.ts
+++ b/src/engine/adapters/wwebjs-labels.ts
@@ -7,7 +7,7 @@ import { isChannelJid, chatKind } from '../identity/wa-id';
import { ChatLabelsUnsupportedError } from '../../common/errors/chat-labels-unsupported.error';
import { LabelNotFoundError } from '../../common/errors/label-not-found.error';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
-import { type WwebjsEngineHost, withPage } from './wwebjs-host';
+import { type WwebjsEngineHost, rethrowIfNavigation, withPage } from './wwebjs-host';
import { isProtocolTimeout } from './wwebjs-lifecycle';
/**
@@ -58,6 +58,7 @@ export class WwebjsLabels {
chats = await (this.client() as unknown as BusinessClient).getChatsByLabelId(labelId);
} catch (error) {
// Same split the group read makes: a dead page is a 503, not "no such label".
+ rethrowIfNavigation(this.host, error);
if (this.host.isPageTransportError(error)) {
this.host.reportIfPageTransportError(error, 'getChatsByLabel');
throw new EngineTransportError(`Transport died while listing chats for label ${labelId}`);
diff --git a/src/engine/adapters/wwebjs-lifecycle.ts b/src/engine/adapters/wwebjs-lifecycle.ts
index 3c64dc991..6813a4048 100644
--- a/src/engine/adapters/wwebjs-lifecycle.ts
+++ b/src/engine/adapters/wwebjs-lifecycle.ts
@@ -69,6 +69,26 @@ export function isProtocolTimeout(error: unknown): boolean {
return PROTOCOL_TIMEOUT_PATTERN.test(error instanceof Error ? error.message : String(error));
}
+/** What a request answers 409 while WhatsApp Web reloads its page, whichever side of the window stamp it lands. */
+export const PAGE_RELOADING_MESSAGE =
+ 'WhatsApp Web is reloading its page and the session is re-injecting. Retry in a few seconds.';
+
+/**
+ * Whether a page call was cut short by the page navigating away under it (WhatsApp Web reloading). Puppeteer
+ * rewrites its three CDP shapes of this into 'Execution context was destroyed, most likely because of a
+ * navigation.', and a call that lands on the new document before WhatsApp Web has booted dies on the missing
+ * `window.require`. The page is alive and re-injecting, so unlike a death this is not reported, and a retry
+ * a few seconds later succeeds. Not an HttpException, and not a failure captured inside the page, whose text
+ * quotes WhatsApp Web and says nothing about our page.
+ */
+export function isNavigationError(error: unknown): boolean {
+ if (error instanceof HttpException) {
+ return false;
+ }
+ const message = error instanceof Error ? error.message : String(error);
+ return !message.startsWith(CAPTURED_PAGE_ERROR_PREFIX) && isNavigationShapedInitRejection(message);
+}
+
/**
* The start of a send failure that scripts/patch-wwebjs-send-error.js captured inside the page, where
* it summarises a thrown value puppeteer would otherwise hand over as `t: t`. The patcher builds the
diff --git a/src/engine/adapters/wwebjs-navigation-error.spec.ts b/src/engine/adapters/wwebjs-navigation-error.spec.ts
new file mode 100644
index 000000000..4e0e78323
--- /dev/null
+++ b/src/engine/adapters/wwebjs-navigation-error.spec.ts
@@ -0,0 +1,186 @@
+import { NotFoundException } from '@nestjs/common';
+import type { Client } from 'whatsapp-web.js';
+import { WwebjsChats } from './wwebjs-chats';
+import { WwebjsContacts } from './wwebjs-contacts';
+import { WwebjsGroups } from './wwebjs-groups';
+import { WwebjsLabels } from './wwebjs-labels';
+import { type WwebjsEngineHost, withPage } from './wwebjs-host';
+import { type WwebjsMessaging } from './wwebjs-messaging';
+import {
+ CAPTURED_PAGE_ERROR_PREFIX,
+ PAGE_RELOADING_MESSAGE,
+ WwebjsLifecycle,
+ isNavigationError,
+} from './wwebjs-lifecycle';
+import { createLogger } from '../../common/services/logger.service';
+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
+import { EngineTransportError } from '../../common/errors/engine-transport.error';
+
+/**
+ * A call already in flight when WhatsApp Web reloads its page dies with Puppeteer's navigation error before
+ * the re-inject window is stamped, so it was a bare 500, and where a catch folds a failed lookup into "not
+ * found" it was a 404 or null for a group, contact or label that exists. The page is alive: nothing is
+ * reported, and the answer is the retryable 409 the adapter already gives inside the window.
+ */
+const logger = createLogger('wwebjs-navigation-error.spec');
+
+const NAVIGATION = 'Execution context was destroyed, most likely because of a navigation.';
+
+describe('isNavigationError', () => {
+ it.each([
+ NAVIGATION,
+ 'Evaluation failed: TypeError: window.require is not a function',
+ 'execution context was destroyed',
+ ])('reads %p as a navigation', message => {
+ expect(isNavigationError(new Error(message))).toBe(true);
+ });
+
+ it('is not a dead page, so the death path never sees it', () => {
+ const pattern = (WwebjsLifecycle as unknown as { PAGE_TRANSPORT_ERROR_PATTERN: RegExp })
+ .PAGE_TRANSPORT_ERROR_PATTERN;
+ expect(pattern.test(NAVIGATION)).toBe(false);
+ });
+
+ it.each([
+ 'Protocol error (Runtime.callFunctionOn): Target closed',
+ "Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls",
+ 'Evaluation failed: TypeError: Cannot read properties of null',
+ '',
+ ])('does not read %p as a navigation', message => {
+ expect(isNavigationError(new Error(message))).toBe(false);
+ });
+
+ it('does not take the words from an error this application built', () => {
+ // MessageNotFoundError and its siblings carry the caller's own text, so a request could name its way in.
+ expect(isNavigationError(new NotFoundException(`Message ${NAVIGATION} not found in chat [email protected]`))).toBe(false);
+ });
+
+ it('does not take the words from a failure captured inside the page', () => {
+ expect(isNavigationError(new Error(`${CAPTURED_PAGE_ERROR_PREFIX}{"message":"${NAVIGATION}"}`))).toBe(false);
+ });
+});
+
+describe('a call the page navigation cut short', () => {
+ const navigation = new Error(NAVIGATION);
+ const ordinary = new Error('Evaluation failed: something else');
+
+ function makeHost(client: unknown): { host: WwebjsEngineHost; reportIfPageTransportError: jest.Mock } {
+ const reportIfPageTransportError = jest.fn();
+ const host = {
+ ensureReady: jest.fn(),
+ getClient: () => client as Client,
+ isPageTransportError: () => false,
+ reportIfPageTransportError,
+ logger,
+ config: {},
+ } as unknown as WwebjsEngineHost;
+ return { host, reportIfPageTransportError };
+ }
+
+ const reload = (): unknown => expect.objectContaining({ message: PAGE_RELOADING_MESSAGE });
+
+ it('withPage answers the 409 and reports nothing', async () => {
+ const { host, reportIfPageTransportError } = makeHost({});
+
+ const result = withPage(host, 'getNumberId', () => Promise.reject(navigation));
+
+ await expect(result).rejects.toBeInstanceOf(EngineNotReadyError);
+ await expect(result).rejects.toEqual(reload());
+ expect(reportIfPageTransportError).not.toHaveBeenCalled();
+ });
+
+ it('a page the host reads as dead stays a death, whatever the message says', async () => {
+ const { host, reportIfPageTransportError } = makeHost({});
+ (host as unknown as { isPageTransportError: () => boolean }).isPageTransportError = () => true;
+
+ await expect(withPage(host, 'getNumberId', () => Promise.reject(navigation))).rejects.toBeInstanceOf(
+ EngineTransportError,
+ );
+ expect(reportIfPageTransportError).toHaveBeenCalledWith(navigation, 'getNumberId');
+ });
+
+ it('withPage still propagates an ordinary failure unchanged', async () => {
+ const { host } = makeHost({});
+
+ await expect(withPage(host, 'getNumberId', () => Promise.reject(ordinary))).rejects.toBe(ordinary);
+ });
+
+ it('the chat and group lists answer the 409', async () => {
+ const client = { info: {}, pupPage: { evaluate: jest.fn().mockRejectedValue(navigation) } };
+ const { host, reportIfPageTransportError } = makeHost(client);
+
+ await expect(new WwebjsChats(host, {} as unknown as WwebjsMessaging).getChats()).rejects.toBeInstanceOf(
+ EngineNotReadyError,
+ );
+ await expect(new WwebjsGroups(host).getGroups()).rejects.toBeInstanceOf(EngineNotReadyError);
+ expect(reportIfPageTransportError).not.toHaveBeenCalled();
+ });
+
+ it('a group read is not "group not found"', async () => {
+ const getChatById = jest.fn().mockRejectedValue(navigation);
+ const { host } = makeHost({ info: {}, getChatById });
+
+ await expect(new WwebjsGroups(host).getGroupInfo('[email protected]')).rejects.toBeInstanceOf(EngineNotReadyError);
+
+ getChatById.mockRejectedValue(ordinary);
+ await expect(new WwebjsGroups(host).getGroupInfo('[email protected]')).resolves.toBeNull();
+ });
+
+ it('an invite preview is not "no such invite"', async () => {
+ const getInviteInfo = jest.fn().mockRejectedValue(navigation);
+ const { host } = makeHost({ getInviteInfo });
+
+ await expect(new WwebjsGroups(host).getGroupJoinInfo('code')).rejects.toBeInstanceOf(EngineNotReadyError);
+ });
+
+ it('an invite acceptance answers the unknown-outcome 503, not an invalid invite', async () => {
+ const acceptInvite = jest.fn().mockRejectedValue(navigation);
+ const { host } = makeHost({ acceptInvite });
+
+ await expect(new WwebjsGroups(host).joinGroupViaInviteCode('code')).rejects.toBeInstanceOf(EngineTransportError);
+ });
+
+ it('a contact read is not "no such contact"', async () => {
+ const getContactById = jest.fn().mockRejectedValue(navigation);
+ const { host } = makeHost({ getContactById });
+
+ await expect(new WwebjsContacts(host).getContactById('[email protected]')).rejects.toBeInstanceOf(EngineNotReadyError);
+
+ getContactById.mockRejectedValue(ordinary);
+ await expect(new WwebjsContacts(host).getContactById('[email protected]')).resolves.toBeNull();
+ });
+
+ it('the contact list, the avatar and the number lookup answer the 409', async () => {
+ const getProfilePicUrl = jest.fn().mockRejectedValue(navigation);
+ const getNumberId = jest.fn().mockRejectedValue(navigation);
+ const client = {
+ info: {},
+ pupPage: { evaluate: jest.fn().mockRejectedValue(navigation) },
+ getProfilePicUrl,
+ getNumberId,
+ };
+ const { host, reportIfPageTransportError } = makeHost(client);
+ const contacts = new WwebjsContacts(host);
+
+ await expect(contacts.getContacts()).rejects.toBeInstanceOf(EngineNotReadyError);
+ await expect(contacts.getProfilePicture('[email protected]')).rejects.toBeInstanceOf(EngineNotReadyError);
+ await expect(contacts.getNumberId('628123')).rejects.toBeInstanceOf(EngineNotReadyError);
+ expect(reportIfPageTransportError).not.toHaveBeenCalled();
+ });
+
+ it('a chat write answers the 409', async () => {
+ const getChatById = jest.fn().mockRejectedValue(navigation);
+ const { host } = makeHost({ getChatById });
+
+ await expect(
+ new WwebjsChats(host, {} as unknown as WwebjsMessaging).muteChat('[email protected]', null),
+ ).rejects.toBeInstanceOf(EngineNotReadyError);
+ });
+
+ it('a label read is not "no such label"', async () => {
+ const getChatsByLabelId = jest.fn().mockRejectedValue(navigation);
+ const { host } = makeHost({ getChatsByLabelId });
+
+ await expect(new WwebjsLabels(host).getChatsByLabel('7')).rejects.toBeInstanceOf(EngineNotReadyError);
+ });
+});