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
Keep connection failure guidance within saved trust and access limits
pulse-triage[bot]60f7d1dc5ff7
diff --git a/frontend-modern/src/components/Settings/ConnectionEditor/__tests__/ConnectionEditor.test.tsx b/frontend-modern/src/components/Settings/ConnectionEditor/__tests__/ConnectionEditor.test.tsxindex 358c89d3ed..a31cb040e7 100644--- a/frontend-modern/src/components/Settings/ConnectionEditor/__tests__/ConnectionEditor.test.tsx+++ b/frontend-modern/src/components/Settings/ConnectionEditor/__tests__/ConnectionEditor.test.tsx@@ -22,6 +22,45 @@ describe('ConnectionEditor', () => {vi.clearAllMocks();});+ it.each([+ [+ 'certificate fingerprint mismatch: expected fixture-old, got fixture-new',+ 'TLS fingerprint changed.',+ 'Keep TLS verification enabled.',+ ],+ [+ 'API error 403: authentication failed',+ 'Permission denied.',+ 'Keep intentional access limits',+ ],+ ])(+ 'renders safe probe guidance and clears it on ordinary recovery: %s',+ async (raw, headline, hint) => {+ mockedProbe.mockRejectedValueOnce(new Error(raw));+ mockedProbe.mockResolvedValueOnce({ candidates: [], probedMs: 10 });+ const renderSlot = vi.fn(() => <div />);+ render(() => <ConnectionEditor renderCredentialSlot={renderSlot} onClose={() => {}} />);+ const input = screen.getByLabelText('API endpoint') as HTMLInputElement;+ fireEvent.input(input, { target: { value: 'https://pve.lab:8006' } });+ fireEvent.click(screen.getByRole('button', { name: /probe api endpoint/i }));+ const alert = await screen.findByRole('alert');+ expect(alert.textContent).toContain(headline);+ expect(alert.textContent).toContain(hint);+ expect(alert.textContent).not.toContain('credentials connected');+ expect(alert.textContent).not.toContain('disable TLS');+ expect(input.value).toBe('https://pve.lab:8006');+ expect(mockedProbe).toHaveBeenCalledTimes(1);+ expect(renderSlot).not.toHaveBeenCalled();++ fireEvent.click(screen.getByRole('button', { name: /probe api endpoint/i }));+ await screen.findByText('No supported API-backed platform detected at that address.');+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ expect(mockedProbe).toHaveBeenCalledTimes(2);+ expect(input.value).toBe('https://pve.lab:8006');+ expect(renderSlot).not.toHaveBeenCalled();+ },+ );+it('runs a probe and dispatches the detected type into the credential slot', async () => {const response: ProbeResponse = {candidates: [diff --git a/frontend-modern/src/components/Settings/__tests__/useConnectionsLedger.branchcov0722am.test.ts b/frontend-modern/src/components/Settings/__tests__/useConnectionsLedger.branchcov0722am.test.tsindex c1cef7d215..001a3f9eb6 100644--- a/frontend-modern/src/components/Settings/__tests__/useConnectionsLedger.branchcov0722am.test.ts+++ b/frontend-modern/src/components/Settings/__tests__/useConnectionsLedger.branchcov0722am.test.ts@@ -279,6 +279,34 @@ describe('connectionToRow (standalone buildRow arms)', () => {const row = connectionToRow(connectionFixture({ lastError: null }));expect(row.lastErrorMessage).toBeUndefined();});++ it.each([+ [+ 'certificate fingerprint mismatch: expected fixture-old, got fixture-new',+ 'TLS fingerprint changed.',+ 'Independently verify its identity',+ ],+ [+ 'API error 403: authentication failed',+ 'Permission denied.',+ 'Keep intentional access limits',+ ],+ ])('presents safe ledger guidance without mutating the connection: %s', (raw, headline, hint) => {+ const connection = connectionFixture({+ state: 'unauthorized',+ scope: { vms: true, containers: false },+ lastError: { message: raw, at: '2026-07-22T12:00:00Z' },+ });+ const original = JSON.stringify(connection);+ const row = connectionToRow(connection);+ expect(row.lastErrorMessage).toContain(headline);+ expect(row.lastErrorMessage).toContain(hint);+ expect(row.lastErrorMessage).not.toContain('disable TLS');+ expect(row.lastErrorMessage).not.toContain('credentials connected');+ expect(row.statusLabel).toBe('Unauthorized');+ expect(JSON.stringify(connection)).toBe(original);+ expect(row.primaryConnection).toBe(connection);+ });});// ---- useConnectionsLedger (systemToRow & row-derivation arms) ---------------diff --git a/frontend-modern/src/utils/__tests__/connectionErrorPresentation.test.ts b/frontend-modern/src/utils/__tests__/connectionErrorPresentation.test.tsindex 54dd56ea45..8cf808ac88 100644--- a/frontend-modern/src/utils/__tests__/connectionErrorPresentation.test.ts+++ b/frontend-modern/src/utils/__tests__/connectionErrorPresentation.test.ts@@ -56,6 +56,90 @@ describe('humanizeConnectionError', () => {expect(result?.headline).toBe('Permission denied');});+ describe('trust-preserving recovery guidance', () => {+ it.each([+ ['x509: certificate signed by unknown authority', 'TLS certificate not trusted'],+ ['x509: certificate has expired or is not yet valid', 'TLS certificate expired'],+ ['remote error: tls: handshake failure', 'TLS handshake failed'],+ [+ 'certificate fingerprint mismatch: expected fixture-old, got fixture-new',+ 'TLS fingerprint changed',+ ],+ ['truenas tls pinning failed: fingerprint mismatch', 'TLS fingerprint changed'],+ [+ 'TLS fingerprint changed - independently verify the certificate before updating the saved fingerprint',+ 'TLS fingerprint changed',+ ],+ ['x509: certificate is valid for old.lab, not new.lab', 'TLS certificate validation failed'],+ [+ 'TLS certificate error - check SSL settings or add fingerprint',+ 'TLS certificate validation failed',+ ],+ ['TLS certificate validation failed', 'TLS certificate validation failed'],+ ])('keeps verification and independently checked identity for %s', (raw, headline) => {+ const result = humanizeConnectionError(raw);+ expect(result?.headline).toBe(headline);+ expect(result?.hint).toContain('Keep TLS verification enabled.');+ expect(result?.hint).toContain('hostname, expiry and trusted chain');+ expect(result?.hint).toContain(+ 'Independently verify its identity before adding or replacing',+ );+ expect(result?.hint).not.toMatch(/disable|temporarily|switch.*HTTP/i);+ });++ it.each([+ 'API error 403: Forbidden',+ 'HTTP status 403: authentication failed; quoted upstream 401',+ 'authentication error: API error 403: invalid credentials',+ 'permission denied',+ ])('does not infer a successful login or prescribe broader access for %s', (raw) => {+ const result = humanizeConnectionError(raw);+ expect(result?.headline).toBe('Permission denied');+ expect(result?.hint).toContain('intended resource');+ expect(result?.hint).toContain('any proxy policy');+ expect(result?.hint).toContain('Keep intentional access limits');+ expect(result?.hint).toContain('do not replace credentials or broaden access just to test');+ expect(result?.hint).not.toMatch(/credentials connected|logged in|Administrator/);+ });++ it.each(['401 Unauthorized', 'authentication failed', 'invalid API token'])(+ 'makes credential replacement conditional for %s',+ (raw) => {+ const result = humanizeConnectionError(raw);+ expect(result?.headline).toBe('Authentication failed');+ expect(result?.hint).toContain('user, realm and token ID');+ expect(result?.hint).toContain('Replace it only if invalidity is confirmed');+ },+ );++ it.each([500, 502, 595])(+ 'does not misclassify HTTP %i provider auth text as a 401',+ (status) => {+ const result = humanizeConnectionError(+ `API error ${status}: Authentication failed; provider mentioned 401 and 403`,+ );+ expect(result?.headline).toBe('Server error');+ expect(result?.hint).not.toMatch(/token|credential/);+ },+ );++ it('ignores status-shaped numbers in the endpoint and poll identity', () => {+ expect(+ humanizeConnectionError(+ 'poll_nodes failed on 401: Get "https://pve.lab:403/api/500": something novel',+ ),+ ).toEqual({ headline: 'something novel', hint: null });+ });++ it.each([400, 429])(+ 'keeps unclassified HTTP %i responses instead of inferring auth failure',+ (status) => {+ const raw = `API error ${status}: provider mentioned 401 Unauthorized`;+ expect(humanizeConnectionError(raw)).toEqual({ headline: raw, hint: null });+ },+ );+ });+it('classifies access violations as blocked connections', () => {const result = humanizeConnectionError('poll_nodes failed on delly: Get "https://delly:8006/api2/json/nodes": Access violation',diff --git a/frontend-modern/src/utils/connectionErrorPresentation.ts b/frontend-modern/src/utils/connectionErrorPresentation.tsindex 23d9424e57..60ebd918f1 100644--- a/frontend-modern/src/utils/connectionErrorPresentation.ts+++ b/frontend-modern/src/utils/connectionErrorPresentation.ts@@ -28,8 +28,29 @@ interface HumanizedConnectionError {const TIMEOUT_HINT ='Check the host is reachable, the port is correct, and the network path is open.';const TLS_HINT =- 'Verify the certificate or pin a fingerprint in TLS settings, or disable TLS verification temporarily for testing.';-const AUTH_HINT = 'Re-check the API token or username/password.';+ "Keep TLS verification enabled. Check the certificate's hostname, expiry and trusted chain. Independently verify its identity before adding or replacing a saved fingerprint.";+const AUTH_HINT =+ 'Check the configured user, realm and token ID, and whether the credential has expired or been revoked. Replace it only if invalidity is confirmed.';+const DENIED_HINT =+ 'Check read permissions for the intended resource and any proxy policy. Keep intentional access limits; do not replace credentials or broaden access just to test.';++const HTTP_STATUS_PRESENTATIONS: Record<number, HumanizedConnectionError> = {+ 401: { headline: 'Authentication failed', hint: AUTH_HINT },+ 403: { headline: 'Permission denied', hint: DENIED_HINT },+ 404: {+ headline: 'Endpoint not found',+ hint: 'Pulse reached the host but the API path is missing. Check the URL path or the platform version.',+ },+};+const SERVER_ERROR: HumanizedConnectionError = {+ headline: 'Server error',+ hint: 'The platform returned a server error. Check the platform logs for the underlying cause.',+};++// Use the first explicit response status, not a number in an endpoint or a+// quoted provider explanation. A 403/5xx mentioning authentication is not a 401.+const HTTP_STATUS_PATTERN =+ /\b(?:API error|HTTP(?: error| status(?: code)?)?|status(?: code)?)[\s:]+([45]\d{2})\b|^([45]\d{2})\b/i;const HUMANIZED_PATTERNS: { match: RegExp; headline: string; hint: string | null }[] = [{@@ -52,6 +73,11 @@ const HUMANIZED_PATTERNS: { match: RegExp; headline: string; hint: string | nullheadline: 'No network route to host',hint: 'The host cannot be reached from this Pulse instance. Check VPN, firewall, or VLAN configuration.',},+ {+ match: /(?:certificate |tls (?:pinning failed: )?)?fingerprint (?:mismatch|changed)/i,+ headline: 'TLS fingerprint changed',+ hint: TLS_HINT,+ },{match: /x509:.*signed by unknown authority|certificate signed by unknown/i,headline: 'TLS certificate not trusted',@@ -68,9 +94,9 @@ const HUMANIZED_PATTERNS: { match: RegExp; headline: string; hint: string | nullhint: TLS_HINT,},{- match: /\b401\b|unauthorized|authentication failed|invalid (?:credentials|api token)/i,- headline: 'Authentication failed',- hint: AUTH_HINT,+ match: /x509:|TLS certificate (?:error|validation failed)/i,+ headline: 'TLS certificate validation failed',+ hint: TLS_HINT,},{match: /access violation/i,@@ -78,19 +104,22 @@ const HUMANIZED_PATTERNS: { match: RegExp; headline: string; hint: string | nullhint: 'The request was blocked before Pulse could read inventory. Check proxy, firewall, or network policy settings.',},{- match: /\b403\b|forbidden|permission denied/i,+ match: /forbidden|permission denied/i,headline: 'Permission denied',- hint: 'The credentials connected, but the user/token lacks the required role.',+ hint: DENIED_HINT,},{- match: /\b404\b|not found/i,- headline: 'Endpoint not found',- hint: 'Pulse reached the host but the API path is missing. Check the URL path or the platform version.',+ match: /unauthorized|authentication failed|invalid (?:credentials|api token)/i,+ headline: 'Authentication failed',+ hint: AUTH_HINT,},{- match: /\b5\d{2}\b|server error|internal error/i,- headline: 'Server error',- hint: 'The platform returned a server error. Check the platform logs for the underlying cause.',+ match: /not found/i,+ ...HTTP_STATUS_PRESENTATIONS[404],+ },+ {+ match: /server error|internal error/i,+ ...SERVER_ERROR,},];@@ -102,15 +131,23 @@ export const humanizeConnectionError = (raw?: string | null): HumanizedConnectioconst trimmed = raw.trim();if (!trimmed) return null;+ const cleaned = stripImplementationPrefixes(trimmed);+ const statusMatch = cleaned.match(HTTP_STATUS_PATTERN);+ if (statusMatch) {+ const status = Number(statusMatch[1] ?? statusMatch[2]);+ const presentation = HTTP_STATUS_PRESENTATIONS[status] ?? (status >= 500 ? SERVER_ERROR : null);+ if (presentation) return { ...presentation };+ return { headline: cleaned, hint: null };+ }+for (const pattern of HUMANIZED_PATTERNS) {- if (pattern.match.test(trimmed)) {+ if (pattern.match.test(cleaned)) {return { headline: pattern.headline, hint: pattern.hint };}}// Unknown error: fall back to the raw text with the most common// implementation-leaking prefixes peeled off so it's at least readable.- const cleaned = stripImplementationPrefixes(trimmed);return { headline: cleaned || 'Connection error', hint: null };};