Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(wwebjs): cache no WA Web build when no version is pinned

Yudhi Armyndharis80501a05bbdc
diff --git a/.env.example b/.env.example
index f5191b272..622f72186 100644
--- a/.env.example
+++ b/.env.example
@@ -171,8 +171,9 @@ OPENWA_PIDS_LIMIT=2048
# it — the pinned HTML is downloaded and executed inside the web.whatsapp.com origin with NO
# integrity check, which is the reliable default (avoids the "stuck at authenticating" hang, #488)
# but means trusting that registry's published HTML. Set "off" to disable pinning and use the
-# first-party build served by WhatsApp (whatsapp-web.js native behavior). Set an exact version
-# string to pin a specific build from the same registry (browse the html/ folder at
+# first-party build served by WhatsApp (whatsapp-web.js native behavior, minus its local HTML
+# cache, which cannot be written in the image). Set an exact version string to pin a specific
+# build from the same registry (browse the html/ folder at
# https://github.com/wppconnect-team/wa-version). WWEBJS_WEB_VERSION_REMOTE_PATH overrides the
# HTML URL template (use {version} as the placeholder) to fetch from an operator-controlled copy
# instead. The active build + its source (pinned/auto/native) is shown on the dashboard's
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 6d1e67fc1..7262b6f77 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -348,7 +348,9 @@ default behaviour rather than the pin you asked for. With
`WWEBJS_WEB_VERSION` unset, `latest`, or `auto` (the default), OpenWA auto-resolves a settled build
from that registry and pins its HTML — note this HTML is fetched from a third-party repository and
executed inside the `web.whatsapp.com` origin without an integrity check. Set
-`WWEBJS_WEB_VERSION=off` to disable pinning and use the first-party build served by WhatsApp.
+`WWEBJS_WEB_VERSION=off` to disable pinning and use the first-party build served by WhatsApp. An
+unpinned session (this setting, or an auto-resolve that could not reach the registry) caches nothing to
+disk, so it also works on the image's read-only root filesystem.
### Issue: QR generation times out on slow first boot (WSL2 / low-resource)
diff --git a/src/engine/adapters/wwebjs-lifecycle.ts b/src/engine/adapters/wwebjs-lifecycle.ts
index 8f83b36fb..e180e6521 100644
--- a/src/engine/adapters/wwebjs-lifecycle.ts
+++ b/src/engine/adapters/wwebjs-lifecycle.ts
@@ -409,7 +409,11 @@ export class WwebjsLifecycle {
},
...(authTimeoutMs !== undefined ? { authTimeoutMs } : {}),
...(proxyAuthentication ? { proxyAuthentication } : {}),
- ...(versionPin ?? {}),
+ // Unpinned, whatsapp-web.js defaults to a local HTML cache at the cwd-relative
+ // './.wwebjs_cache/' and writes it after the link, before `ready`. The image's /app is not
+ // writable (root-owned, read-only in compose and Helm), so that write throws and the session
+ // never reaches ready. 'none' caches nothing and serves WhatsApp's live build.
+ ...(versionPin ?? { webVersionCache: { type: 'none' as const } }),
});
this.client = client;
diff --git a/src/engine/adapters/wwebjs-web-version-cache.spec.ts b/src/engine/adapters/wwebjs-web-version-cache.spec.ts
new file mode 100644
index 000000000..2f54c3d8a
--- /dev/null
+++ b/src/engine/adapters/wwebjs-web-version-cache.spec.ts
@@ -0,0 +1,48 @@
+import { Client } from 'whatsapp-web.js';
+import { WhatsAppWebJsAdapter } from './whatsapp-web-js.adapter';
+
+/**
+ * The web version cache handed to the whatsapp-web.js Client. Unpinned, the library's default is a
+ * local cache written to a cwd-relative directory after the link; in the container that directory
+ * is not writable, the write throws before `ready`, and the session never becomes ready.
+ */
+describe('whatsapp-web.js web version cache', () => {
+ let clientInitSpy: jest.SpyInstance;
+ let savedWebVersion: string | undefined;
+
+ const launchedCacheOption = async (webVersion: string): Promise<unknown> => {
+ process.env.WWEBJS_WEB_VERSION = webVersion;
+ const adapter = new WhatsAppWebJsAdapter({
+ sessionId: 'sess-web-version-cache',
+ sessionDataPath: './data/sessions',
+ puppeteer: {},
+ });
+ await adapter.initialize({});
+ return (adapter as unknown as { client: { options: { webVersionCache: unknown } } }).client.options.webVersionCache;
+ };
+
+ beforeEach(() => {
+ savedWebVersion = process.env.WWEBJS_WEB_VERSION;
+ // Build the real Client, whose options are merged over the library defaults, but launch no browser.
+ clientInitSpy = jest
+ .spyOn(Client.prototype as unknown as { initialize: () => Promise<void> }, 'initialize')
+ .mockResolvedValue(undefined);
+ });
+
+ afterEach(() => {
+ clientInitSpy.mockRestore();
+ if (savedWebVersion === undefined) {
+ delete process.env.WWEBJS_WEB_VERSION;
+ } else {
+ process.env.WWEBJS_WEB_VERSION = savedWebVersion;
+ }
+ });
+
+ it('caches nothing to disk when no build is pinned', async () => {
+ expect(await launchedCacheOption('off')).toEqual({ type: 'none' });
+ });
+
+ it('keeps the remote cache for a pinned build', async () => {
+ expect(await launchedCacheOption('2.3000.1000000000')).toMatchObject({ type: 'remote' });
+ });
+});