Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(dashboard): show the gateway's advice on an incomplete force-kill

Yudhi Armyndharisd5115f6dc440
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27a491b8f..9742639de 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -168,7 +168,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- A session stopped while it was starting or reconnecting no longer reads `initializing` until the next restart.
- A stop and start issued while a reconnect was still tearing down the old engine no longer leaves a second engine running on the same account.
- Stop, logout, force-kill and delete no longer fail with `500` when the session's pending `initializing` status write hit a database error.
-- `POST /api/sessions/:sessionId/force-kill` answers `502` with `code: SESSION_FORCE_KILL_INCOMPLETE` when the engine could not be killed, instead of reporting a clean kill; the session is still marked `disconnected`.
+- `POST /api/sessions/:sessionId/force-kill` answers `502` with `code: SESSION_FORCE_KILL_INCOMPLETE` when the engine could not be killed, instead of reporting a clean kill; the session is still marked `disconnected`, and the dashboard shows the gateway's advice to restart the node.
- A session stopped or restarted during a lease heartbeat is no longer reported as a lost lease, which could tear down its restarting engine.
- A WhatsApp restriction imposed again after the previous one expired raises `session.restriction` again, with its WebSocket event and audit row.
- Engines write session credentials under `SESSION_DATA_PATH` or `BAILEYS_AUTH_DIR` even when an engine config saved with `PUT /api/plugins/:id/config` names another path, so the owner-only permissions and the session-delete purge cover them.
diff --git a/dashboard/src/pages/Sessions.test.ts b/dashboard/src/pages/Sessions.test.ts
index 094cc43de..bd1838eec 100644
--- a/dashboard/src/pages/Sessions.test.ts
+++ b/dashboard/src/pages/Sessions.test.ts
@@ -101,6 +101,7 @@ function resetFetchCalls(): void {
startGate = null;
startResult = null;
stopFailure = null;
+ forceKillFailure = null;
qrGate = null;
listGate = null;
pairingGate = null;
@@ -133,6 +134,8 @@ let startFailure: { status: number; message: string; leaves?: Partial<Session> }
let startResult: { answer: Partial<Session>; leaves?: Partial<Session> } | null = null;
// When set, POST .../stop answers with this error.
let stopFailure: { status: number; message: string } | null = null;
+// When set, POST .../force-kill answers with this status and body.
+let forceKillFailure: { status: number; body: Record<string, unknown> } | null = null;
// When set, POST .../start answers, whichever way it answers, only once this settles.
let startGate: Promise<void> | null = null;
// When set, GET .../qr for that one session answers only once `until` settles.
@@ -283,6 +286,9 @@ function installFetchStub(): void {
if (lifecycleMatch[2] === 'stop' && stopFailure) {
return jsonResponse({ message: stopFailure.message }, stopFailure.status);
}
+ if (lifecycleMatch[2] === 'force-kill' && forceKillFailure) {
+ return jsonResponse(forceKillFailure.body, forceKillFailure.status);
+ }
if (isStart && startResult) {
const answered = { ...base, ...startResult.answer };
if (found) Object.assign(found, startResult.leaves ?? startResult.answer);
@@ -1774,3 +1780,34 @@ test('a failed stop is reported instead of only logged', async () => {
within(alert).getByText('Stop Failed');
within(alert).getByText('Session is busy');
});
+
+// The session is already stopped when the gateway reports the kill incomplete, so the toast carries its
+// guidance. A 502 without that code may come from a reverse proxy and stays generic.
+for (const [label, body, shown] of [
+ [
+ 'a force-kill the gateway reports incomplete shows its guidance',
+ { message: 'Engine process may still be running. Restart the node.', code: 'SESSION_FORCE_KILL_INCOMPLETE' },
+ 'Engine process may still be running. Restart the node.',
+ ],
+ [
+ 'a force-kill 502 without the gateway code stays generic',
+ { message: 'Bad Gateway' },
+ 'Failed to force-kill the session.',
+ ],
+] as const) {
+ test(label, async () => {
+ const { screen, fireEvent, within } = rtl;
+ resetFetchCalls();
+ forceKillFailure = { status: 502, body };
+ renderSessions();
+
+ const card = (await screen.findByText('stale-engine')).closest('.session-card') as HTMLElement;
+ fireEvent.click(within(card).getByRole('button', { name: 'Kill Stuck' }));
+ fireEvent.click(within(await screen.findByRole('dialog')).getByRole('button', { name: 'Kill Session' }));
+
+ const alert = await screen.findByRole('alert');
+ assert.ok(alert.classList.contains('toast-error'), 'the force-kill failure was not shown as an error toast');
+ within(alert).getByText('Force-Kill Failed');
+ within(alert).getByText(shown);
+ });
+}
diff --git a/dashboard/src/pages/Sessions.tsx b/dashboard/src/pages/Sessions.tsx
index b7a56e89d..c0af4cfbc 100644
--- a/dashboard/src/pages/Sessions.tsx
+++ b/dashboard/src/pages/Sessions.tsx
@@ -566,7 +566,14 @@ export function Sessions() {
toast.success(t('sessions.forceKill.successTitle'), t('sessions.forceKill.success'));
} catch (err) {
console.error('Failed to force-kill:', err);
- toast.error(t('sessions.forceKill.failedTitle'), t('sessions.forceKill.failed'));
+ // 502 + SESSION_FORCE_KILL_INCOMPLETE: the session is stopped, but the engine process may still
+ // run. Show the gateway's guidance (restart the node). Any other error, a reverse-proxy 502
+ // without that code included, stays generic.
+ const incomplete = (err as { code?: string } | null)?.code === 'SESSION_FORCE_KILL_INCOMPLETE';
+ toast.error(
+ t('sessions.forceKill.failedTitle'),
+ incomplete && err instanceof Error && err.message ? err.message : t('sessions.forceKill.failed'),
+ );
await fetchSessions();
} finally {
setKillConfirmId(null);