Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(config): document and forward BAILEYS_CHAT_STATE_CACHE_MAX

Yudhi Armyndharisdd3d9debdb1c
diff --git a/.env.example b/.env.example
index 57e900c60..1e22f7d18 100644
--- a/.env.example
+++ b/.env.example
@@ -264,6 +264,11 @@ OPENWA_PIDS_LIMIT=2048
# re-resolution, or a defined empty result, so eviction never loses data. 0 disables the cap. Default 5000.
# BAILEYS_SESSION_STORE_MAX_ENTRIES=5000
+# Global cap on the in-memory Baileys chat mute/archive/pin mirror, shared by all sessions. An evicted
+# row stays persisted and is read back from the database on a miss, so eviction never loses data. Raise
+# it for many sessions or large chat lists. 0 disables the cap. Default 5000.
+# BAILEYS_CHAT_STATE_CACHE_MAX=5000
+
# Per-session cap on the Baileys message rows kept in the database: the newest N survive and older
# rows are pruned after each write. A non-positive or non-numeric value falls back to the default.
# BAILEYS_MESSAGE_STORE_LIMIT=5000
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ce9b6e97..d39310fa2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- 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)).
- A session that runs out of reconnect attempts fires the `session:error` plugin hook when it lands in `failed`.
- An explicit `maxReconnectAttempts` is honoured and the reconnect delay is capped at 5 minutes; the budget used to restart once the backoff passed 5 minutes, so the limit was never reached and the documented 1-hour cap never applied.
+- `BAILEYS_CHAT_STATE_CACHE_MAX` is listed in `.env.example` and forwarded by both bundled Compose files, so the Baileys chat-state cache cap can be raised from `.env`.
## [0.23.5] - 2026-09-14
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index d4de2b9a3..b5857e463 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -236,6 +236,7 @@ services:
- BAILEYS_LOG_LEVEL=${BAILEYS_LOG_LEVEL:-}
- BAILEYS_MESSAGE_STORE_LIMIT=${BAILEYS_MESSAGE_STORE_LIMIT:-}
- BAILEYS_SESSION_STORE_MAX_ENTRIES=${BAILEYS_SESSION_STORE_MAX_ENTRIES:-}
+ - BAILEYS_CHAT_STATE_CACHE_MAX=${BAILEYS_CHAT_STATE_CACHE_MAX:-}
- WWEBJS_ONBOARDING_CONTINUE_LABELS=${WWEBJS_ONBOARDING_CONTINUE_LABELS:-}
# Default matches the image's ENV (Dockerfile); a blank forward would shadow it and make
# puppeteer fall back to a bundled Chromium the image does not ship. compose-parity.spec.ts
diff --git a/docker-compose.yml b/docker-compose.yml
index 2d2211d2a..ed008a12e 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -336,6 +336,7 @@ services:
- BAILEYS_LOG_LEVEL=${BAILEYS_LOG_LEVEL:-}
- BAILEYS_MESSAGE_STORE_LIMIT=${BAILEYS_MESSAGE_STORE_LIMIT:-}
- BAILEYS_SESSION_STORE_MAX_ENTRIES=${BAILEYS_SESSION_STORE_MAX_ENTRIES:-}
+ - BAILEYS_CHAT_STATE_CACHE_MAX=${BAILEYS_CHAT_STATE_CACHE_MAX:-}
- WWEBJS_ONBOARDING_CONTINUE_LABELS=${WWEBJS_ONBOARDING_CONTINUE_LABELS:-}
# Default matches the image's ENV (Dockerfile); a blank forward would shadow it and make
# puppeteer fall back to a bundled Chromium the image does not ship. compose-parity.spec.ts
diff --git a/src/config/env-precedence.ts b/src/config/env-precedence.ts
index 7fb43e09e..702c6d4e9 100644
--- a/src/config/env-precedence.ts
+++ b/src/config/env-precedence.ts
@@ -200,6 +200,7 @@ export const BLANK_SHADOWED_ENV_KEYS: string[] = [
'BAILEYS_LOG_LEVEL',
'BAILEYS_MESSAGE_STORE_LIMIT',
'BAILEYS_SESSION_STORE_MAX_ENTRIES',
+ 'BAILEYS_CHAT_STATE_CACHE_MAX',
'WWEBJS_ONBOARDING_CONTINUE_LABELS',
'SHUTDOWN_DELAY_MS',
'SIMULATE_TYPING_MAX_MS',