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 agent update failures before another manual attempt
pulse-triage[bot]455a23acf963
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex 69a547ed0d..d6045c6ea6 100644--- a/docs/UNIFIED_AGENT.md+++ b/docs/UNIFIED_AGENT.md@@ -857,9 +857,11 @@ new version is available:5. Replaces itself atomically (with backup)6. Restarts with the same configuration-Use the manual update path for v5 agents, PVE host agents, agents with-auto-update disabled, and agents blocked by authentication, missing connection-state, download, trust, or self-test failures. Open an outdated-agent notice or+Use the manual update path for v5 agents, PVE host agents and agents with+auto-update disabled. For a failed or uncertain update, first follow+[Agent Not Updating](#agent-not-updating); a manual command is not a diagnostic+retry or a repair for every automatic-update failure. For a planned manual+update, open an outdated-agent notice or`/settings/infrastructure?agentDoctor=1` to open **Agent Doctor** andcopy the command for each reported host. Pulse does not remotely execute thosecommands.@@ -1385,18 +1387,46 @@ space problem is resolved; verify fresh reporting, free space and log growthafter any planned repair. Keep log contents, connection files and tokens private.### Agent Not Updating-- Inspect existing errors with the [bounded agent log reader](#collect-agent-logs-safely);- a missing update entry is not proof that an update succeeded.-- Verify network connectivity to Pulse server-- Ensure auto-update is not disabled-- Confirm the agent can authenticate and that its saved connection state still- identifies the Pulse URL and token.-- Open **Agent Doctor** from an outdated-agent notice or- `/settings/infrastructure?agentDoctor=1` and use the command for that reported- host. Do not substitute the public GitHub server installer.-- Administrators can query the read-only Agent Fleet Doctor endpoint,- `GET /api/agents/diagnostics`, for liveness, version, profile, telemetry, and- identity evidence. The endpoint reports repair handoffs but does not run them.++Keep the server's update target, the agent's last reported version and the+result of an update attempt separate. Updating Pulse does not prove an agent+updated; a stale report does not establish what is running now. Read the+[existing version and Last seen displays](TROUBLESHOOTING.md#find-the-running-server-and-agent-versions)+and **Agent Doctor** for the affected host. Unknown is valid; do not restart+or repeat an update to fill the gap.++1. **Before download:** distinguish an offline or stale agent, an intentional+ auto-update opt-out, and an authentication or saved-connection error. Use+ existing Doctor findings and the [bounded agent log reader](#collect-agent-logs-safely).+ A missing update entry is not proof of success. For a rejected report, use+ [reporting checks](#agent-lookup-returns-http-401-or-403); do not replace a+ token, delete connection state or re-enrol the host just to test it.+2. **Download, validation or helper staging:** keep the original failure stage+ and exact redacted error. A successful checksum, signature or self-test+ does not establish activation. For example, the typed helper's+ `signed artifact is not the requested pulse-agent version` error is a+ later version-validation rejection, not a signature-verification failure.+ Keep the requested and reported candidate versions, including any `v`+ prefix, only if already available. Do not bypass signature checks, relax+ permissions or replace the helper manually to force acceptance.+3. **Activation, restart or rollback:** an accepted download or staged artifact+ is not a completed update. Preserve the original result and any rollback+ error, then compare fresh reporting from that same host with the intended+ version. A healthy Doctor view after a manual update does not prove future+ automatic updates work. Do not repeat the attempt while its result or+ installed state is uncertain.++If a copied manual command stopped at preflight or its private prompt, use+[command preparation checks](#copied-agent-command-fails-before-installation).+That is a separate failure from the automatic updater; passing preflight is+not installation. Do not substitute the public GitHub server installer or+change the installed privilege profile to get past an agent-update error.++If the error remains, add the original stage, redacted error and known versions+to the [existing report or help thread](TROUBLESHOOTING.md#-getting-help),+including recovery already performed. Keep tokens, full copied commands,+connection files and service environments private. No new update, Diagnostics+run or full configuration export is required to ask for help.### Duplicate Agentsdiff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex 69a547ed0d..d6045c6ea6 100644--- a/frontend-modern/public/docs/UNIFIED_AGENT.md+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md@@ -857,9 +857,11 @@ new version is available:5. Replaces itself atomically (with backup)6. Restarts with the same configuration-Use the manual update path for v5 agents, PVE host agents, agents with-auto-update disabled, and agents blocked by authentication, missing connection-state, download, trust, or self-test failures. Open an outdated-agent notice or+Use the manual update path for v5 agents, PVE host agents and agents with+auto-update disabled. For a failed or uncertain update, first follow+[Agent Not Updating](#agent-not-updating); a manual command is not a diagnostic+retry or a repair for every automatic-update failure. For a planned manual+update, open an outdated-agent notice or`/settings/infrastructure?agentDoctor=1` to open **Agent Doctor** andcopy the command for each reported host. Pulse does not remotely execute thosecommands.@@ -1385,18 +1387,46 @@ space problem is resolved; verify fresh reporting, free space and log growthafter any planned repair. Keep log contents, connection files and tokens private.### Agent Not Updating-- Inspect existing errors with the [bounded agent log reader](#collect-agent-logs-safely);- a missing update entry is not proof that an update succeeded.-- Verify network connectivity to Pulse server-- Ensure auto-update is not disabled-- Confirm the agent can authenticate and that its saved connection state still- identifies the Pulse URL and token.-- Open **Agent Doctor** from an outdated-agent notice or- `/settings/infrastructure?agentDoctor=1` and use the command for that reported- host. Do not substitute the public GitHub server installer.-- Administrators can query the read-only Agent Fleet Doctor endpoint,- `GET /api/agents/diagnostics`, for liveness, version, profile, telemetry, and- identity evidence. The endpoint reports repair handoffs but does not run them.++Keep the server's update target, the agent's last reported version and the+result of an update attempt separate. Updating Pulse does not prove an agent+updated; a stale report does not establish what is running now. Read the+[existing version and Last seen displays](TROUBLESHOOTING.md#find-the-running-server-and-agent-versions)+and **Agent Doctor** for the affected host. Unknown is valid; do not restart+or repeat an update to fill the gap.++1. **Before download:** distinguish an offline or stale agent, an intentional+ auto-update opt-out, and an authentication or saved-connection error. Use+ existing Doctor findings and the [bounded agent log reader](#collect-agent-logs-safely).+ A missing update entry is not proof of success. For a rejected report, use+ [reporting checks](#agent-lookup-returns-http-401-or-403); do not replace a+ token, delete connection state or re-enrol the host just to test it.+2. **Download, validation or helper staging:** keep the original failure stage+ and exact redacted error. A successful checksum, signature or self-test+ does not establish activation. For example, the typed helper's+ `signed artifact is not the requested pulse-agent version` error is a+ later version-validation rejection, not a signature-verification failure.+ Keep the requested and reported candidate versions, including any `v`+ prefix, only if already available. Do not bypass signature checks, relax+ permissions or replace the helper manually to force acceptance.+3. **Activation, restart or rollback:** an accepted download or staged artifact+ is not a completed update. Preserve the original result and any rollback+ error, then compare fresh reporting from that same host with the intended+ version. A healthy Doctor view after a manual update does not prove future+ automatic updates work. Do not repeat the attempt while its result or+ installed state is uncertain.++If a copied manual command stopped at preflight or its private prompt, use+[command preparation checks](#copied-agent-command-fails-before-installation).+That is a separate failure from the automatic updater; passing preflight is+not installation. Do not substitute the public GitHub server installer or+change the installed privilege profile to get past an agent-update error.++If the error remains, add the original stage, redacted error and known versions+to the [existing report or help thread](TROUBLESHOOTING.md#-getting-help),+including recovery already performed. Keep tokens, full copied commands,+connection files and service environments private. No new update, Diagnostics+run or full configuration export is required to ask for help.### Duplicate Agentsdiff --git a/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts b/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.tsindex 64c5d2dabf..bec05f0602 100644--- a/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts+++ b/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts@@ -149,3 +149,68 @@ describe('Stopped agent-command help', () => {}});});++describe('Agent update failure help', () => {+ const section = () => docSection(source, 'UNIFIED_AGENT', 'agent-not-updating');++ it('separates update stages and manual recovery from future automatic updating', () => {+ const help = section();+ const text = help.textContent!.replace(/\s+/g, ' ');+ const steps = [...help.querySelectorAll(':scope > ol > li')];+ expect(steps.map((step) => step.querySelector('strong')?.textContent)).toEqual([+ 'Before download:',+ 'Download, validation or helper staging:',+ 'Activation, restart or rollback:',+ ]);+ for (const fact of [+ "the server's update target, the agent's last reported version",+ 'a stale report does not establish what is running now',+ 'A successful checksum, signature or self-test does not establish activation',+ 'signed artifact is not the requested pulse-agent version',+ 'not a signature-verification failure',+ 'A healthy Doctor view after a manual update does not prove future automatic updates work',+ 'passing preflight is not installation',+ ]) {+ expect(text).toContain(fact);+ }+ });++ it('offers existing evidence and safe destinations instead of a diagnostic update recipe', () => {+ const help = section();+ const text = help.textContent!.replace(/\s+/g, ' ');+ const article = document.createElement('article');+ article.innerHTML = renderDocMarkdown(source, 'UNIFIED_AGENT');+ for (const id of [+ 'collect-agent-logs-safely',+ 'agent-lookup-returns-http-401-or-403',+ 'copied-agent-command-fails-before-installation',+ ]) {+ expect(help.querySelector(`a[href="#${id}"]`)).not.toBeNull();+ expect(article.querySelector(`#${id}`)).not.toBeNull();+ }+ for (const id of ['find-the-running-server-and-agent-versions', '-getting-help']) {+ expect(help.querySelector(`a[href="/docs/TROUBLESHOOTING#${id}"]`)).not.toBeNull();+ }+ expect(help.querySelector('pre')).toBeNull();+ for (const boundary of [+ 'do not restart or repeat an update to fill the gap',+ 'Do not bypass signature checks, relax permissions or replace the helper manually',+ 'Do not repeat the attempt while its result or installed state is uncertain',+ 'Keep tokens, full copied commands, connection files and service environments private',+ 'No new update, Diagnostics run or full configuration export is required',+ ]) {+ expect(text).toContain(boundary);+ }+ });++ it('routes failed automatic updates to investigation before a planned manual update', () => {+ const autoUpdate = docSection(source, 'UNIFIED_AGENT', 'auto-update');+ expect(autoUpdate.querySelector('a[href="#agent-not-updating"]')).not.toBeNull();+ expect(autoUpdate.textContent!.replace(/\s+/g, ' ')).toContain(+ 'a manual command is not a diagnostic retry or a repair for every automatic-update failure',+ );+ expect(readFileSync(path.join(frontendRoot, 'public/docs/UNIFIED_AGENT.md'), 'utf8')).toBe(+ source,+ );+ });+});