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
Make safe troubleshooting paths reachable from the first screen
pulse-triage[bot]c46190050949
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 1ab6df91f3..5292d79942 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -1,5 +1,55 @@# 🔧 Troubleshooting Guide+## Choose the affected workflow++Start with the symptom below, using observations you already have. A restart,+reinstall or new diagnostic run is not a prerequisite for getting help.++**If a guest is unresponsive, a backup is in freeze/thaw, or an earlier guest+request's state is uncertain, read [Backup safety](VM_DISK_MONITORING.md#backup-safety)+first.** Do not run Diagnostics, force guest-agent probes or repeat a backup to+fill a report. A successful backup task or responsive console alone does not+establish safe recovery.++- **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+ or repeat first-time setup.+- **Update failed or its result is uncertain:** start with+ [Pulse server update checks](AUTO_UPDATE.md#update-failed). An update of a+ monitored container is a different job; use+ [Docker workload update checks](DOCKER.md#check-a-failed-or-pending-workload-update).+ Preserve the current state and rollback evidence; do not repeat the attempt.+- **Agent host is missing or reporting is rejected:** check the existing+ [agent authentication and reporting evidence](UNIFIED_AGENT.md#agent-lookup-returns-http-401-or-403)+ before replacing a token or reinstalling. Installer success is not an accepted+ report.+- **Guest readings are missing or disagree:** distinguish+ [current, retained and unavailable disks](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings)+ from [guest memory pressure](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).+ Unknown is not zero, and a working Pulse Agent view does not prove API recovery.+- **Proxmox data belongs to the wrong host, or healthy jobs look Pending:** use+ [cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations)+ or [replication status checks](TROUBLESHOOTING.md#replication-jobs-are-pending-stale-or-missing).+ Do not rename, remove or re-enrol resources to create evidence.+- **TrueNAS readings are stale or absent:** use+ [TrueNAS data checks](TRUENAS.md#stale-truenas-data), keeping the platform API+ and Pulse Agent paths separate.+- **Pulse itself uses more memory, CPU or disk writes:** use+ [memory baseline and growth checks](TROUBLESHOOTING.md#memory-use-keeps-growing)+ or [CPU and write-rate checks](TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth).+ Guest usage and database size are different measurements.+- **Notification Test works but alerts do not arrive:** follow+ [ordinary delivery checks](TROUBLESHOOTING.md#test-succeeds-but-real-alerts-are-missing).+ Do not trigger an alert or replay the queue just to complete a report.+- **Private information was posted:** follow+ [disclosure containment](TROUBLESHOOTING.md#if-you-already-posted-private-information).+ Deleting the public copy does not revoke a credential.++If none fits, use [Getting Help](TROUBLESHOOTING.md#-getting-help).+Review evidence locally before sharing it; unknown or unavailable details are+valid, and a full configuration, journal or network export is not required.+## ⚡ Quick Fixes### I forgot my passworddiff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.mdindex 1ab6df91f3..5292d79942 100644--- a/frontend-modern/public/docs/TROUBLESHOOTING.md+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md@@ -1,5 +1,55 @@# 🔧 Troubleshooting Guide+## Choose the affected workflow++Start with the symptom below, using observations you already have. A restart,+reinstall or new diagnostic run is not a prerequisite for getting help.++**If a guest is unresponsive, a backup is in freeze/thaw, or an earlier guest+request's state is uncertain, read [Backup safety](VM_DISK_MONITORING.md#backup-safety)+first.** Do not run Diagnostics, force guest-agent probes or repeat a backup to+fill a report. A successful backup task or responsive console alone does not+establish safe recovery.++- **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+ or repeat first-time setup.+- **Update failed or its result is uncertain:** start with+ [Pulse server update checks](AUTO_UPDATE.md#update-failed). An update of a+ monitored container is a different job; use+ [Docker workload update checks](DOCKER.md#check-a-failed-or-pending-workload-update).+ Preserve the current state and rollback evidence; do not repeat the attempt.+- **Agent host is missing or reporting is rejected:** check the existing+ [agent authentication and reporting evidence](UNIFIED_AGENT.md#agent-lookup-returns-http-401-or-403)+ before replacing a token or reinstalling. Installer success is not an accepted+ report.+- **Guest readings are missing or disagree:** distinguish+ [current, retained and unavailable disks](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings)+ from [guest memory pressure](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).+ Unknown is not zero, and a working Pulse Agent view does not prove API recovery.+- **Proxmox data belongs to the wrong host, or healthy jobs look Pending:** use+ [cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations)+ or [replication status checks](TROUBLESHOOTING.md#replication-jobs-are-pending-stale-or-missing).+ Do not rename, remove or re-enrol resources to create evidence.+- **TrueNAS readings are stale or absent:** use+ [TrueNAS data checks](TRUENAS.md#stale-truenas-data), keeping the platform API+ and Pulse Agent paths separate.+- **Pulse itself uses more memory, CPU or disk writes:** use+ [memory baseline and growth checks](TROUBLESHOOTING.md#memory-use-keeps-growing)+ or [CPU and write-rate checks](TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth).+ Guest usage and database size are different measurements.+- **Notification Test works but alerts do not arrive:** follow+ [ordinary delivery checks](TROUBLESHOOTING.md#test-succeeds-but-real-alerts-are-missing).+ Do not trigger an alert or replay the queue just to complete a report.+- **Private information was posted:** follow+ [disclosure containment](TROUBLESHOOTING.md#if-you-already-posted-private-information).+ Deleting the public copy does not revoke a credential.++If none fits, use [Getting Help](TROUBLESHOOTING.md#-getting-help).+Review evidence locally before sharing it; unknown or unavailable details are+valid, and a full configuration, journal or network export is not required.+## ⚡ Quick Fixes### I forgot my passworddiff --git a/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts b/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.tsnew file mode 100644index 0000000000..168ee8554e--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts@@ -0,0 +1,111 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import { renderDocMarkdown, stripLeadingTitle } from '../docMarkdown';++const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');+const shippedDocs = path.join(repoRoot, 'frontend-modern/public/docs');+const source = readFileSync(path.join(shippedDocs, 'TROUBLESHOOTING.md'), 'utf8');++function renderGuide(name: string, markdown?: string): HTMLElement {+ const article = document.createElement('article');+ article.innerHTML = renderDocMarkdown(+ stripLeadingTitle(markdown ?? readFileSync(path.join(shippedDocs, `${name}.md`), 'utf8')),+ name,+ );+ return article;+}++function entry(): HTMLElement {+ const article = renderGuide('TROUBLESHOOTING', source);+ const heading = article.querySelector('h2');+ expect(heading?.id).toBe('choose-the-affected-workflow');+ const section = document.createElement('section');+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {+ if (next.tagName === 'H2') break;+ section.appendChild(next.cloneNode(true));+ }+ return section;+}++const prose = (element: HTMLElement): string =>+ (element.textContent ?? '').replace(/\s+/g, ' ').trim();++describe('troubleshooting workflow entry', () => {+ it('puts guest incident safety before the symptom links and any collection recipe', () => {+ const section = entry();+ const link = section.querySelector('a');+ expect(link?.getAttribute('href')).toBe('/docs/VM_DISK_MONITORING#backup-safety');+ expect(section.querySelectorAll('li')).toHaveLength(9);+ expect(section.querySelector('pre')).toBeNull();+ const beforeList = [...section.children]+ .slice(+ 0,+ [...section.children].findIndex((element) => element.tagName === 'UL'),+ )+ .map((element) => prose(element as HTMLElement))+ .join(' ');+ expect(beforeList).toContain("an earlier guest request's state is uncertain");+ expect(beforeList).toContain(+ 'Do not run Diagnostics, force guest-agent probes or repeat a backup',+ );+ expect(beforeList).toContain('responsive console alone does not establish safe recovery');+ });++ it('keeps server updates, workload updates and reporting acceptance distinct', () => {+ const section = entry();+ const rows = section.querySelectorAll('li');+ expect(prose(rows[1] as HTMLElement)).toContain(+ 'An update of a monitored container is a different job',+ );+ const updateLinks = [...rows[1].querySelectorAll('a')].map((link) => link.getAttribute('href'));+ expect(updateLinks).toEqual([+ '/docs/AUTO_UPDATE#update-failed',+ '/docs/DOCKER#check-a-failed-or-pending-workload-update',+ ]);+ expect(prose(rows[1] as HTMLElement)).toContain(+ 'Preserve the current state and rollback evidence',+ );+ expect(prose(rows[2] as HTMLElement)).toContain('Installer success is not an accepted report');+ expect(prose(rows[3] as HTMLElement)).toContain(+ 'a working Pulse Agent view does not prove API recovery',+ );+ expect(prose(rows[6] as HTMLElement)).toContain(+ 'Guest usage and database size are different measurements',+ );+ });++ it('routes every entry to an existing shipped heading in the production viewer', () => {+ const links = [...entry().querySelectorAll('a[href]')];+ expect(links).toHaveLength(16);+ for (const link of links) {+ const href = link.getAttribute('href')!;+ const match = /^\/docs\/([^#]+)#(.+)$/.exec(href);+ expect(match, href).not.toBeNull();+ const target = renderGuide(match![1]).querySelector(`[id="${match![2]}"]`);+ expect(target, href).not.toBeNull();+ expect(target?.tagName, href).toMatch(/^H[1-6]$/);+ expect(link.hasAttribute('data-doc-link'), href).toBe(true);+ expect(link.hasAttribute('target'), href).toBe(false);+ }+ });++ it('keeps the source and shipped entry identical and preserves existing anchors', () => {+ const canonical = readFileSync(path.join(repoRoot, 'docs/TROUBLESHOOTING.md'), 'utf8');+ expect(source).toBe(canonical);+ const article = renderGuide('TROUBLESHOOTING');+ for (const id of [+ 'i-forgot-my-password',+ 'memory-use-keeps-growing',+ 'collect-diagnostics-safely',+ 'recovery-mode',+ '-getting-help',+ ]) {+ expect(article.querySelector(`[id="${id}"]`), id).not.toBeNull();+ }+ expect(prose(entry())).toContain('unknown or unavailable details are valid');+ expect(prose(entry())).toContain('Deleting the public copy does not revoke a credential');+ expect(prose(entry())).toContain('Do not trigger an alert or replay the queue');+ });+});