Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Explain why green health can accompany a stalled dashboard
pulse-triage[bot]da25a6e88c44
diff --git a/docs/API.md b/docs/API.mdindex def600fa83..eda7cd1492 100644--- a/docs/API.md+++ b/docs/API.md@@ -207,17 +207,38 @@ reports, accept tokens bound to that organization with the listed scope.## 📡 Core Endpoints### System Health-`GET /api/health`-Check if Pulse is running.+`GET /api/health` (also accepts `HEAD`)++Public server liveness response: `200` for the handler's healthy condition,+`503` for its unhealthy condition. A GET response can include:+```json{"status": "healthy","timestamp": 1700000000,"uptime": 3600,- "devModeSSH": false+ "devModeSSH": false,+ "dependencies": {+ "monitor": true,+ "scheduler": true,+ "websocket": true+ }}```+**Liveness is not end-to-end readiness.** A `200`, `"status": "healthy"`, or+true dependency flags do not establish successful authentication, current+polling, delivery of dashboard state over `/ws`, or notification delivery.+In particular, `websocket: true` is not proof that a browser received its+initial state; a successful WebSocket upgrade or welcome message is not that+proof either. A container health badge based only on this endpoint inherits+these limits.++If health is green while the dashboard is stuck or stale, use the+[stalled-dashboard guidance](TROUBLESHOOTING.md#health-is-green-but-the-dashboard-is-stalled).+Do not add repeated state requests or an automatic restart loop to turn this+limited check into a readiness test; preserve the original failure evidence.+### System State`GET /api/state`Returns the complete state of your infrastructure (Nodes, VMs, Containers, Storage, Alerts). This is the main endpoint used by the dashboard.diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex a45d665af2..c8903393a1 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -14,6 +14,9 @@ establish safe recovery.- **Not sure which version is affected:** distinguish the[running server, reported agent and update target](TROUBLESHOOTING.md#find-the-running-server-and-agent-versions).A helper's selected release or an agent's target is not its running version.+- **Dashboard is stuck on “Connecting to Pulse” or stops updating:** distinguish+ [server liveness from dashboard delivery](#health-is-green-but-the-dashboard-is-stalled).+ Green health is not proof that current readings reached your browser.- **Cannot sign in:** use [local password recovery](TROUBLESHOOTING.md#i-forgot-my-password)or [401 and login failures](TROUBLESHOOTING.md#cannot-login--401-unauthorized),according to the existing authentication method. Do not delete configuration@@ -276,6 +279,36 @@ do not replace credentials or disable TLS verification on a refusal alone.For a page that opens but has missing readings, use the[missing-data checks](FAQ.md#no-data-showing) instead of resetting the connection.+### Health is green but the dashboard is stalled++A public [`/api/health` response](API.md#system-health) checks limited server+liveness, not end-to-end readiness. HTTP `200`, `"status": "healthy"` or a+container's **healthy** badge can coexist with “Connecting to Pulse”, no initial+state or stale readings. They do not verify sign-in, recent platform polling,+dashboard-state delivery or notification delivery.++Use observations from the original failure, not a new diagnostic run:++| Existing observation | What it establishes — and what it does not |+| --- | --- |+| Pulse's page does not open | Check the [installation and service distinction](INSTALL.md#installation-did-not-reach-a-usable-server) and [connection path](#connection-refused). A healthy response from another address, proxy or earlier time does not establish this page's availability. |+| Sign-in succeeds and the page stays on “Connecting to Pulse” | Authentication worked for that attempt; the dashboard still did not become usable. A successful `/ws` upgrade or welcome message opens the transport, but does not establish receipt of initial state. It does not identify a lock owner or prove a proxy, browser-cache or credential fault. |+| The dashboard opens but readings stop advancing | Compare the affected resource's last visible observation with the original incident time. An open connection does not prove that collection or delivery continues; a current value, a retained value and stored History are separate evidence. Follow the [missing-data checks](FAQ.md#no-data-showing) for the affected source. |++Keep the failure time and timezone, running server version and exact displayed+message when already available. If you already have browser network evidence,+retain only the relevant request path, status and timing or redacted error.+Keep cookies, headers, query values, WebSocket frames, full responses and network+exports private; do not use **Copy as cURL**. An unavailable observation is+unknown, not success or an empty infrastructure list.++Do not restart, reinstall, clear browser storage, sign out, bypass the proxy,+disable TLS or run Diagnostics just to demonstrate recovery. Do not send+repeated state requests, induce a freeze or take a process-terminating dump to+recreate the incident. Preserve existing configuration, credentials and logs;+[report the evidence already available](#-getting-help). A later recovery does+not explain the earlier failure, and this guidance is not a runtime fix.+### Proxmox or PBS certificate validation failedA TLS error is not an invalid API token or a missing permission. Keep thediff --git a/frontend-modern/public/docs/API.md b/frontend-modern/public/docs/API.mdindex def600fa83..eda7cd1492 100644--- a/frontend-modern/public/docs/API.md+++ b/frontend-modern/public/docs/API.md@@ -207,17 +207,38 @@ reports, accept tokens bound to that organization with the listed scope.## 📡 Core Endpoints### System Health-`GET /api/health`-Check if Pulse is running.+`GET /api/health` (also accepts `HEAD`)++Public server liveness response: `200` for the handler's healthy condition,+`503` for its unhealthy condition. A GET response can include:+```json{"status": "healthy","timestamp": 1700000000,"uptime": 3600,- "devModeSSH": false+ "devModeSSH": false,+ "dependencies": {+ "monitor": true,+ "scheduler": true,+ "websocket": true+ }}```+**Liveness is not end-to-end readiness.** A `200`, `"status": "healthy"`, or+true dependency flags do not establish successful authentication, current+polling, delivery of dashboard state over `/ws`, or notification delivery.+In particular, `websocket: true` is not proof that a browser received its+initial state; a successful WebSocket upgrade or welcome message is not that+proof either. A container health badge based only on this endpoint inherits+these limits.++If health is green while the dashboard is stuck or stale, use the+[stalled-dashboard guidance](TROUBLESHOOTING.md#health-is-green-but-the-dashboard-is-stalled).+Do not add repeated state requests or an automatic restart loop to turn this+limited check into a readiness test; preserve the original failure evidence.+### System State`GET /api/state`Returns the complete state of your infrastructure (Nodes, VMs, Containers, Storage, Alerts). This is the main endpoint used by the dashboard.diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.mdindex a45d665af2..c8903393a1 100644--- a/frontend-modern/public/docs/TROUBLESHOOTING.md+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md@@ -14,6 +14,9 @@ establish safe recovery.- **Not sure which version is affected:** distinguish the[running server, reported agent and update target](TROUBLESHOOTING.md#find-the-running-server-and-agent-versions).A helper's selected release or an agent's target is not its running version.+- **Dashboard is stuck on “Connecting to Pulse” or stops updating:** distinguish+ [server liveness from dashboard delivery](#health-is-green-but-the-dashboard-is-stalled).+ Green health is not proof that current readings reached your browser.- **Cannot sign in:** use [local password recovery](TROUBLESHOOTING.md#i-forgot-my-password)or [401 and login failures](TROUBLESHOOTING.md#cannot-login--401-unauthorized),according to the existing authentication method. Do not delete configuration@@ -276,6 +279,36 @@ do not replace credentials or disable TLS verification on a refusal alone.For a page that opens but has missing readings, use the[missing-data checks](FAQ.md#no-data-showing) instead of resetting the connection.+### Health is green but the dashboard is stalled++A public [`/api/health` response](API.md#system-health) checks limited server+liveness, not end-to-end readiness. HTTP `200`, `"status": "healthy"` or a+container's **healthy** badge can coexist with “Connecting to Pulse”, no initial+state or stale readings. They do not verify sign-in, recent platform polling,+dashboard-state delivery or notification delivery.++Use observations from the original failure, not a new diagnostic run:++| Existing observation | What it establishes — and what it does not |+| --- | --- |+| Pulse's page does not open | Check the [installation and service distinction](INSTALL.md#installation-did-not-reach-a-usable-server) and [connection path](#connection-refused). A healthy response from another address, proxy or earlier time does not establish this page's availability. |+| Sign-in succeeds and the page stays on “Connecting to Pulse” | Authentication worked for that attempt; the dashboard still did not become usable. A successful `/ws` upgrade or welcome message opens the transport, but does not establish receipt of initial state. It does not identify a lock owner or prove a proxy, browser-cache or credential fault. |+| The dashboard opens but readings stop advancing | Compare the affected resource's last visible observation with the original incident time. An open connection does not prove that collection or delivery continues; a current value, a retained value and stored History are separate evidence. Follow the [missing-data checks](FAQ.md#no-data-showing) for the affected source. |++Keep the failure time and timezone, running server version and exact displayed+message when already available. If you already have browser network evidence,+retain only the relevant request path, status and timing or redacted error.+Keep cookies, headers, query values, WebSocket frames, full responses and network+exports private; do not use **Copy as cURL**. An unavailable observation is+unknown, not success or an empty infrastructure list.++Do not restart, reinstall, clear browser storage, sign out, bypass the proxy,+disable TLS or run Diagnostics just to demonstrate recovery. Do not send+repeated state requests, induce a freeze or take a process-terminating dump to+recreate the incident. Preserve existing configuration, credentials and logs;+[report the evidence already available](#-getting-help). A later recovery does+not explain the earlier failure, and this guidance is not a runtime fix.+### Proxmox or PBS certificate validation failedA TLS error is not an invalid API token or a missing permission. Keep thediff --git a/frontend-modern/src/features/docs/__tests__/dashboardReadinessGuide.test.ts b/frontend-modern/src/features/docs/__tests__/dashboardReadinessGuide.test.tsnew file mode 100644index 0000000000..d86f22e5e8--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/dashboardReadinessGuide.test.ts@@ -0,0 +1,84 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { describe, expect, it } from 'vitest';+import { renderDocMarkdown } from '../docMarkdown';++const read = (file: string) => readFileSync(path.resolve(process.cwd(), '..', file), 'utf8');+const anchor = 'health-is-green-but-the-dashboard-is-stalled';+const guide = (name: string) => read(`docs/${name}.md`);+const article = (markdown: string, name: string) => {+ const element = document.createElement('article');+ element.innerHTML = renderDocMarkdown(markdown, name);+ return element;+};+// Render the real section, not an invented diagnostic page or source-code spelling.+const section = (name: string, heading: string) => {+ const markdown = guide(name).split(`### ${heading}\n`)[1]?.split('\n### ')[0];+ expect(markdown, heading).toBeDefined();+ return article(`### ${heading}\n${markdown}`, name);+};+const text = (node: HTMLElement) => node.textContent!.replace(/\s+/g, ' ').trim();+const stalled = () => section('TROUBLESHOOTING', 'Health is green but the dashboard is stalled');++describe('dashboard readiness guidance', () => {+ it('offers a real symptom entry and working two-way API links', () => {+ const entry = guide('TROUBLESHOOTING').split('\n## ⚡ Quick Fixes')[0];+ const rendered = article(entry, 'TROUBLESHOOTING');+ const links = rendered.querySelectorAll(`a[href="#${anchor}"]`);+ expect(links).toHaveLength(1);+ expect(text(links[0].closest('li')!)).toMatch(/Connecting to Pulse.*stops updating/);+ expect(stalled().querySelector(`#${anchor}`)?.tagName).toBe('H3');+ expect(stalled().querySelector('a[href="/docs/API#system-health"]')).not.toBeNull();+ const health = section('API', 'System Health');+ expect(health.querySelector('#system-health')?.tagName).toBe('H3');+ expect(health.querySelector(`a[href="/docs/TROUBLESHOOTING#${anchor}"]`)).not.toBeNull();+ });++ it('separates public liveness and dependency presence from usable dashboard delivery', () => {+ const health = section('API', 'System Health');+ const copy = text(health);+ expect(copy).toMatch(/GET \/api\/health.*HEAD/);+ expect(copy).toMatch(/Public.*200.*503/);+ expect(copy).toMatch(/Liveness is not end-to-end readiness/);+ expect(copy).toMatch(/do not establish.*authentication.*polling.*dashboard state.*notification/);+ expect(copy).toMatch(/websocket: true is not proof.*initial state/);+ expect(copy).toMatch(/upgrade or welcome message is not that proof/);+ expect(copy).toMatch(/container health badge.*inherits these limits/);+ const example = JSON.parse(health.querySelector('pre code')!.textContent!);+ expect(example.dependencies).toEqual({ monitor: true, scheduler: true, websocket: true });+ expect(example.status).toBe('healthy');+ });++ it('keeps connection, authentication, initial state and advancing readings distinct', () => {+ const rendered = stalled();+ const rows = [...rendered.querySelectorAll('tbody tr')];+ expect(rows).toHaveLength(3);+ expect(text(rows[0])).toMatch(/page does not open.*another address, proxy or earlier time/);+ expect(text(rows[1])).toMatch(/Sign-in succeeds.*Authentication worked.*does not establish receipt of initial state/);+ expect(text(rows[1])).toMatch(/does not identify a lock owner.*proxy, browser-cache or credential fault/);+ expect(text(rows[2])).toMatch(/readings stop advancing.*collection or delivery continues/);+ expect(text(rows[2])).toMatch(/current value.*retained value.*stored History/);+ expect(rendered.querySelector('a[href="/docs/FAQ#no-data-showing"]')).not.toBeNull();+ expect(rendered.querySelector('a[href="/docs/INSTALL#installation-did-not-reach-a-usable-server"]')).not.toBeNull();+ expect(rendered.querySelector('a[href="#connection-refused"]')).not.toBeNull();+ });++ it('uses existing evidence without extra probes, reset advice or credential-bearing exports', () => {+ const rendered = stalled();+ const copy = text(rendered);+ expect(rendered.querySelector('pre')).toBeNull();+ expect(copy).toMatch(/original failure, not a new diagnostic run/);+ expect(copy).toMatch(/when already available/);+ expect(copy).toMatch(/cookies, headers, query values, WebSocket frames, full responses.*exports private/);+ expect(copy).toMatch(/do not use Copy as cURL/);+ expect(copy).toMatch(/unavailable observation is unknown, not success/);+ expect(copy).toMatch(/Do not restart, reinstall, clear browser storage, sign out, bypass the proxy, disable TLS or run Diagnostics/);+ expect(copy).toMatch(/Do not send repeated state requests, induce a freeze or take a process-terminating dump/);+ expect(copy).toMatch(/Preserve existing configuration, credentials and logs/);+ expect(copy).toMatch(/guidance is not a runtime fix/);+ expect(rendered.querySelector('a[href="#-getting-help"]')).not.toBeNull();+ for (const name of ['API', 'TROUBLESHOOTING']) {+ expect(read(`frontend-modern/public/docs/${name}.md`)).toBe(guide(name));+ }+ });+});diff --git a/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts b/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.tsindex e4ef20bbad..8b94565ff9 100644--- a/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts+++ b/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts@@ -90,6 +90,10 @@ describe('troubleshooting workflow entry', () => {'Unraid reports missing disks in empty slots:',['/docs/TROUBLESHOOTING#unraid-reports-missing-disks-in-empty-slots'],],+ [+ 'Dashboard is stuck on “Connecting to Pulse” or stops updating:',+ ['#health-is-green-but-the-dashboard-is-stalled'],+ ],['Cannot sign in:',[