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 saved and uncertain configuration import failures
pulse-triage[bot]488106ceb060
diff --git a/docs/API.md b/docs/API.mdindex 0157440994..d773cfd990 100644--- a/docs/API.md+++ b/docs/API.md@@ -800,6 +800,19 @@ Request body:}```+Import replaces the included settings; it is not an idempotent merge. HTTP 500+can follow a **saved** archive when live apply fails. In particular,+`Configuration saved, but live reload failed:` names the affected live+components, not a rejected file or rollback. Other components may already have+applied. Do not automatically retry this POST after an error or lost response.++HTTP 409 can mean an import is still running or the same backup was submitted+recently. It does not establish the original attempt's outcome. The duplicate+guard is temporary and process-local; waiting or restarting does not make a+retry safe. Follow the [saved-or-uncertain import checks](MIGRATION.md#when-an-import-fails-or-times-out)+before another submission or migration cutover. Preserve the redacted error,+not the archive, passphrase or raw configuration, in a report.+---## 🧭 Setup & Discoverydiff --git a/docs/MIGRATION.md b/docs/MIGRATION.mdindex ce48a17ce2..8a20cd4989 100644--- a/docs/MIGRATION.md+++ b/docs/MIGRATION.md@@ -122,14 +122,46 @@ configuration import as proof of a complete multi-organisation migration.and enter its passphrase. Import replaces the included configuration andAPI-token records; it does not merge them with the destination's records.4. Check the result before changing DNS or agent addresses. A success message- establishes neither full recovery nor fresh monitoring. If import reports a- reload/apply failure, settings may already have been written: preserve both- installations and inspect the error before repeating it.+ establishes neither full recovery nor fresh monitoring. For a reload/apply+ error, timeout or duplicate-request warning, follow [the failure checks+ below](#when-an-import-fails-or-times-out) before retrying or cutting over.Keep the archive, passphrase, configuration files and credentials out of issuethreads. Use the authenticated settings form rather than a command containinga password, API token or session cookie.+### When an import fails or times out++**A failed response is not a rollback.** Keep both installations and the+destination's pre-import backup. Distinguish these outcomes:++- **Archive rejected:** check the original file and passphrase against the+ reported error. Do not delete destination data or regenerate encryption keys.+- **Saved, but not applied:** `Configuration saved, but live reload failed:`+ means the imported settings are on disk, but the named live components did+ not all reload. The list can name alert settings, webhook settings, email+ settings or guest metadata; other components may already have applied.+ Older messages `Configuration imported but failed to reload` and+ `Configuration imported but failed to apply changes` also follow a saved+ import. **Do not repeat the import.** It can overwrite legitimate changes+ made since the first attempt; the error does not mean the old settings were+ restored.+- **No final response, or HTTP 409:** a timeout, lost connection or recently+ submitted/still-running warning does not establish whether the original+ import saved or applied. Do not resubmit it to discover the outcome. The+ duplicate-request guard is temporary and process-local, not a durable+ rollback or permission to retry after waiting or restarting.++Keep the destination isolated from providers, agents, notifications and remote+actions while reconciling a migration trial. Preserve the redacted error and+check the **same destination and organisation**, using destination-local+administrator access. Review the saved settings and the reported component's+failure through normal maintenance before relying on it; a saved email or+webhook destination does not prove notification delivery. Do not restart Pulse,+send a test notification or repeat a backup just to clear the error. Resume the+[single-owner handover](#hand-over-monitoring-once) only after the failed apply+has been resolved; if its state remains uncertain, do not enable a second poller.+## Cut over and verify### Hand over monitoring oncediff --git a/frontend-modern/public/docs/API.md b/frontend-modern/public/docs/API.mdindex 0157440994..d773cfd990 100644--- a/frontend-modern/public/docs/API.md+++ b/frontend-modern/public/docs/API.md@@ -800,6 +800,19 @@ Request body:}```+Import replaces the included settings; it is not an idempotent merge. HTTP 500+can follow a **saved** archive when live apply fails. In particular,+`Configuration saved, but live reload failed:` names the affected live+components, not a rejected file or rollback. Other components may already have+applied. Do not automatically retry this POST after an error or lost response.++HTTP 409 can mean an import is still running or the same backup was submitted+recently. It does not establish the original attempt's outcome. The duplicate+guard is temporary and process-local; waiting or restarting does not make a+retry safe. Follow the [saved-or-uncertain import checks](MIGRATION.md#when-an-import-fails-or-times-out)+before another submission or migration cutover. Preserve the redacted error,+not the archive, passphrase or raw configuration, in a report.+---## 🧭 Setup & Discoverydiff --git a/frontend-modern/public/docs/MIGRATION.md b/frontend-modern/public/docs/MIGRATION.mdindex ce48a17ce2..8a20cd4989 100644--- a/frontend-modern/public/docs/MIGRATION.md+++ b/frontend-modern/public/docs/MIGRATION.md@@ -122,14 +122,46 @@ configuration import as proof of a complete multi-organisation migration.and enter its passphrase. Import replaces the included configuration andAPI-token records; it does not merge them with the destination's records.4. Check the result before changing DNS or agent addresses. A success message- establishes neither full recovery nor fresh monitoring. If import reports a- reload/apply failure, settings may already have been written: preserve both- installations and inspect the error before repeating it.+ establishes neither full recovery nor fresh monitoring. For a reload/apply+ error, timeout or duplicate-request warning, follow [the failure checks+ below](#when-an-import-fails-or-times-out) before retrying or cutting over.Keep the archive, passphrase, configuration files and credentials out of issuethreads. Use the authenticated settings form rather than a command containinga password, API token or session cookie.+### When an import fails or times out++**A failed response is not a rollback.** Keep both installations and the+destination's pre-import backup. Distinguish these outcomes:++- **Archive rejected:** check the original file and passphrase against the+ reported error. Do not delete destination data or regenerate encryption keys.+- **Saved, but not applied:** `Configuration saved, but live reload failed:`+ means the imported settings are on disk, but the named live components did+ not all reload. The list can name alert settings, webhook settings, email+ settings or guest metadata; other components may already have applied.+ Older messages `Configuration imported but failed to reload` and+ `Configuration imported but failed to apply changes` also follow a saved+ import. **Do not repeat the import.** It can overwrite legitimate changes+ made since the first attempt; the error does not mean the old settings were+ restored.+- **No final response, or HTTP 409:** a timeout, lost connection or recently+ submitted/still-running warning does not establish whether the original+ import saved or applied. Do not resubmit it to discover the outcome. The+ duplicate-request guard is temporary and process-local, not a durable+ rollback or permission to retry after waiting or restarting.++Keep the destination isolated from providers, agents, notifications and remote+actions while reconciling a migration trial. Preserve the redacted error and+check the **same destination and organisation**, using destination-local+administrator access. Review the saved settings and the reported component's+failure through normal maintenance before relying on it; a saved email or+webhook destination does not prove notification delivery. Do not restart Pulse,+send a test notification or repeat a backup just to clear the error. Resume the+[single-owner handover](#hand-over-monitoring-once) only after the failed apply+has been resolved; if its state remains uncertain, do not enable a second poller.+## Cut over and verify### Hand over monitoring oncediff --git a/frontend-modern/src/features/docs/__tests__/configurationImportOutcomeDocs.test.ts b/frontend-modern/src/features/docs/__tests__/configurationImportOutcomeDocs.test.tsnew file mode 100644index 0000000000..e805130025--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/configurationImportOutcomeDocs.test.ts@@ -0,0 +1,126 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import { createGuideFixture } from './guideFixture';++const frontendRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');+const repoRoot = path.resolve(frontendRoot, '..');+const readDoc = (name: string) => readFileSync(path.join(repoRoot, 'docs', `${name}.md`), 'utf8');+const articleFor = createGuideFixture(readDoc);+const textOf = (element: Element) => element.textContent!.replace(/\s+/g, ' ');++function failureSection() {+ const heading = articleFor('MIGRATION').querySelector('#when-an-import-fails-or-times-out');+ expect(heading).not.toBeNull();+ const section = document.createElement('section');+ for (+ let node = heading!.nextElementSibling;+ node && !/^H[23]$/.test(node.tagName);+ node = node.nextElementSibling+ ) {+ section.append(node.cloneNode(true));+ }+ return section;+}++describe('Configuration import outcome guidance', () => {+ it('routes an unsuccessful transfer to outcome checks before cutover', () => {+ const article = articleFor('MIGRATION');+ const resultStep = article.querySelector(+ '#transfer-the-included-configuration + ol > li:nth-child(4)',+ );+ expect(resultStep?.querySelector('a')?.getAttribute('href')).toBe(+ '#when-an-import-fails-or-times-out',+ );+ const headings = [...article.querySelectorAll('h2, h3')].map((heading) => heading.id);+ expect(headings.indexOf('when-an-import-fails-or-times-out')).toBeLessThan(+ headings.indexOf('cut-over-and-verify'),+ );+ expect(textOf(failureSection())).toContain('A failed response is not a rollback');+ });++ it('matches the producer errors without mistaking a saved archive for a rejection', () => {+ const source = readFileSync(+ path.join(repoRoot, 'internal/api/configapi/config_export_import_handlers.go'),+ 'utf8',+ );+ const section = failureSection();+ const code = [...section.querySelectorAll('code')].map((node) => node.textContent!);+ for (const message of [+ 'Configuration saved, but live reload failed:',+ 'Configuration imported but failed to reload',+ 'Configuration imported but failed to apply changes',+ ]) {+ expect(source).toContain(message);+ expect(code).toContain(message);+ }+ const componentNames = [+ ...source.matchAll(/reloadFailures = append\(reloadFailures, "([^"]+)"\)/g),+ ].map((match) => match[1]);+ expect(new Set(componentNames).size).toBe(4);+ for (const component of componentNames) expect(textOf(section)).toContain(component);+ const text = textOf(section);+ expect(text).toContain('imported settings are on disk');+ expect(text).toContain('other components may already have applied');+ expect(text).toContain('Do not repeat the import');+ expect(text).toContain('overwrite legitimate changes made since the first attempt');+ });++ it('treats lost responses and duplicate guards as uncertainty, not a retry timer', () => {+ const text = textOf(failureSection());+ expect(text).toContain('No final response, or HTTP 409');+ expect(text).toContain('does not establish whether the original import saved or applied');+ expect(text).toContain('Do not resubmit it to discover the outcome');+ expect(text).toContain('temporary and process-local');+ expect(text).toContain('not a durable rollback or permission to retry');+ expect(text).toContain('waiting or restarting');+ });++ it('preserves isolated, same-organisation recovery without induced side effects', () => {+ const section = failureSection();+ const text = textOf(section);+ expect(text).toContain("destination's pre-import backup");+ expect(text).toContain('isolated from providers, agents, notifications and remote actions');+ expect(text).toContain('same destination and organisation');+ expect(text).toContain('destination-local administrator access');+ expect(text).toContain('does not prove notification delivery');+ expect(text).toContain('Do not restart Pulse, send a test notification or repeat a backup');+ expect(text).toContain('do not enable a second poller');+ expect(section.querySelector('pre, form, input, button')).toBeNull();+ const handover = section.querySelector('a[href="#hand-over-monitoring-once"]');+ expect(handover).not.toBeNull();+ expect(articleFor('MIGRATION').querySelector('#hand-over-monitoring-once')).not.toBeNull();+ });++ it('documents non-idempotent API outcomes with a working reader-facing recovery link', () => {+ const article = articleFor('API');+ const heading = article.querySelector('#import-configuration');+ expect(heading).not.toBeNull();+ const section = document.createElement('section');+ for (+ let node = heading!.nextElementSibling;+ node && !/^H[23]$/.test(node.tagName);+ node = node.nextElementSibling+ ) {+ section.append(node.cloneNode(true));+ }+ const text = textOf(section);+ expect(text).toContain('not an idempotent merge');+ expect(text).toContain('HTTP 500 can follow a saved archive');+ expect(text).toContain('Do not automatically retry this POST');+ expect(text).toContain('HTTP 409');+ expect(text).toContain('not the archive, passphrase or raw configuration');+ expect(+ section.querySelector('a[href="/docs/MIGRATION#when-an-import-fails-or-times-out"]'),+ ).not.toBeNull();+ });++ it('ships the exact migration and API guidance used by the renderer tests', () => {+ for (const name of ['MIGRATION', 'API']) {+ expect(readFileSync(path.join(frontendRoot, 'public/docs', `${name}.md`), 'utf8')).toBe(+ readDoc(name),+ );+ }+ });+});