[Bug]: Persisted whatsapp-web.js session falls back to QR after restart with no LOGOUT audit

[htooumm]

OpenWA version

v0.23.0

Deployment

• Coolify / Docker Compose
• PostgreSQL and Redis
• whatsapp-web.js engine
• Persistent named volume: openwa-data:/app/data
• Six sessions
• AUTO_START_SESSIONS=true
• STATUS_SEED_ON_READY=false
• WWEBJS_AUTH_TIMEOUT_MS=120000
• stop_grace_period: 45s
• 7 GB memory limit and 4096 PID limit

What happened?

One session (rashed) was paired and worked normally for approximately three days with a low-volume webhook bot. Other sessions in the same container also worked normally.

After an OpenWA update/restart, this session required a new QR while the other sessions restored successfully. It was re-paired and worked again. After upgrading to v0.23.0 it initially remained connected, but following a later host restart the same session again returned to QR.

The persistent LocalAuth directory was not deleted:

/app/data/sessions/session-rashed
Size: 449M

Default/Cookies: present
Default/Local Storage: present
Default/IndexedDB: present

The session was active shortly before restart, but on startup it initialized and generated a QR instead of reaching ready:

Auto-starting 6 previously authenticated session(s)
Auto-starting 6 previously authenticated session(s)
Initializing engine for session: rashed
Auto-start failed for session: rashed
trace: Session is already starting
QR code generated
Auto-started session: rashed

The other five sessions reached ready from the same persistent volume.

The terminal-unlink audit query returned no records:

{"data":[],"total":0}

There was no observed LOGOUT, UNPAIRED, auth_failure, credential-cleanup warning, or profile error in the available logs. After stopping the QR-ready engine, the session row became:

{
  "status": "disconnected",
  "phone": null,
  "lastError": null,
  "engineLoaded": false
}

The first QR after restart appeared before any manual Stop/Start attempts. Multiple later session_qr_generated audit rows were periodic QR refreshes while the pairing screen remained open, not confirmed QR scans.

Expected behavior

A previously authenticated session with a populated LocalAuth directory should restore after a normal restart without requiring another QR, as the other sessions do.

If the stored authentication is unusable, OpenWA should expose whether this was:

• a WhatsApp-side revocation while the process was offline;
• a LocalAuth/profile restoration failure;
• or an incompatible/corrupted Chromium profile.

Reporting auto_start_success after reaching only the QR screen is also unclear.

Questions

1. How can a populated LocalAuth profile return directly to QR without a terminal-unlink audit record?
2. Could the duplicate auto-start invocation contribute, even though the second attempt is rejected with Session is already starting?
3. What additional diagnostics can distinguish an offline WhatsApp revocation from a LocalAuth restoration failure?
4. Is there a safe way to prevent automatic QR/re-pair loops for a previously authenticated session until an operator reviews the failure?

[MLuc24]

The give-away is in the log you pasted, and it is easy to read past: the auto-start banner appears twice.

Auto-starting 6 previously authenticated session(s)
Auto-starting 6 previously authenticated session(s)

That line is logged once per run of autoStartSessions(), so two runs each enumerated the same six sessions and both went for rashed. The rest of the trace is the losing side of that race — Session is already starting, auto-start failed, QR generated.

The code says outright why this matters, right above the query:

// Restricted to sessions this node may claim. Without it every replica scans the same rows and
// races to launch the same engines, which is a WhatsApp account being opened twice, not merely
// duplicated work.
const claimable = this.ownership?.claimableWhere() ?? [{}];

Note the fallback. If this.ownership is undefined the where-clause becomes [{}] — unrestricted — and every node happily claims every session. So the guard against exactly your symptom is opt-in on ownership being wired up.

This also explains the two things that make it look mysterious. There is no LOGOUT audit because nothing logged out: WhatsApp invalidated the credentials because the account was opened twice, which is not an event OpenWA sees as a logout. And the LocalAuth directory is intact at 449M because nothing deleted it — a second Chromium attaching to the same profile does not remove files, it just leaves the pairing unusable.

Your deployment makes the overlap easy to hit, which fits the timing you describe. Both incidents happened on a restart or an update, and with stop_grace_period: 45s on Coolify the outgoing container can still be alive — still holding those Chromium profiles on the shared openwa-data volume — while the replacement starts and runs its own auto-start. Two containers, one volume, six sessions each.

Two things worth checking before assuming a whatsapp-web.js persistence bug. First, whether ownership is actually configured in your setup, since without it the claim filter does nothing. Second, whether your redeploy genuinely serialises: watch whether the old container has exited before the new one logs its auto-start banner, rather than assuming the grace period is enough. Six sessions with a 2s throttle between Chromium launches means the run takes at least ten seconds, so a 45-second overlap window is comfortably long enough for both to be inside it.

If it turns out two containers were up at once, the fix is on the deployment side rather than the session side, and re-pairing will keep being undone until that is closed off.

[rmyndharis]

Thanks for the thorough report. Taking your questions in order, with what the code actually does. Two of the things you surfaced were real gaps on our side and are fixed on main.

Q2, the doubled "Auto-starting 6" line. That was a bug, present since v0.19.0, and not specific to your setup: SessionService was exposed to the plugin runtime through a second provider token, and Nest ran its lifecycle hooks once per provider, so the boot hook fired twice and two auto-start loops raced over the same six rows. The loser was refused before it touched anything ("Session is already starting"), so each session still got exactly one engine and this could not delete or replace credentials, but it defeated the 2 s stagger between Chromium launches and printed a spurious "Auto-start failed" per session. Fixed in #1448; from the next release those lines disappear.

Q1 and Q3, why there is no unlink record and how to tell the cases apart. The session_disconnected audit row is only written when a running engine sees WhatsApp unlink it. If the pairing was revoked while the container was down, the next start simply finds WhatsApp Web unpaired and shows a QR: no LOGOUT, no auth_failure (that event cannot fire with LocalAuth at all), no credential cleanup, and the profile directory stays fully populated. That is exactly the shape you captured. A Chromium profile whose IndexedDB state was lost by an unclean exit produces the identical shape, so the logs alone cannot separate the two. Also, "Auto-started session" only means the engine finished initializing, which for whatsapp-web.js happens as soon as the first QR is emitted; it is not a "ready" signal.

Because that transition was invisible, #1452 adds a warning: a previously linked session that comes back asking for a QR now logs relink_required naming the likely causes and the check to make. What still discriminates today:

1. On the phone, Settings > Linked devices at the moment of the restart. Device gone = WhatsApp revoked it (this also happens after ~14 days offline). Device still listed while OpenWA shows a QR = the local profile lost its keys.
2. How the previous container ended: docker inspect <old container> --format '{{.State.ExitCode}} {{.State.OOMKilled}}' (137 means it was killed after the grace period) and the tail of its log around "Graceful shutdown requested". A SIGTERM that lands while boot auto-start is still launching sessions can exceed 45 s, after which Docker kills every Chromium mid-write.
3. uname -m on the host. On amd64 the bundled Chromium has not changed since v0.8.12; on arm64 the image installs Debian's unpinned chromium, so a rebuild can change the browser major.
4. Next time it happens, copy the profile aside before starting the session again (cp -a /app/data/sessions/session-rashed /app/data/quarantine-rashed); the next start overwrites the evidence.

One detail worth checking on your side: POST /stop does not clear phone, so the phone: null you saw means a logout ran at some point after boot (the dashboard Logout button, or the API). Which action did you use?

Q4, stopping the re-pair loop. There is no per-session auto-start switch today. Auto-start picks every session with a phone and status disconnected, and a session parked at the QR screen is reset to disconnected on the next boot, so it comes back to QR on every restart until it is re-paired, logged out (which clears phone), deleted, or AUTO_START_SESSIONS=false globally. A per-session opt-out is a reasonable request; if you open it as a feature issue we can track it there.

[htooumm]

Thank you for the detailed, code-level explanation and for addressing both gaps so quickly — I genuinely appreciate the care you put into reviewing the report.

To answer your question: I only used Stop, followed by Start, from the dashboard. I did not use Logout, Unlink, Delete, Kill Stuck, or the logout API. The first QR had already been generated by auto-start before my manual actions.

When I checked Linked Devices later, after the account review, the OpenWA device was no longer listed. I did not check it at the exact moment of restart, so I cannot confirm when it disappeared.

I’ll wait for the next release containing #1448 and #1452. Thanks again for the clear explanation and quick fixes.