Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Explain saved and uncertain configuration import failures

pulse-triage[bot]488106ceb060
diff --git a/docs/API.md b/docs/API.md
index 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 & Discovery
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
index 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 and
API-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 issue
threads. Use the authenticated settings form rather than a command containing
a 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 once
diff --git a/frontend-modern/public/docs/API.md b/frontend-modern/public/docs/API.md
index 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 & Discovery
diff --git a/frontend-modern/public/docs/MIGRATION.md b/frontend-modern/public/docs/MIGRATION.md
index 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 and
API-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 issue
threads. Use the authenticated settings form rather than a command containing
a 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 once
diff --git a/frontend-modern/src/features/docs/__tests__/configurationImportOutcomeDocs.test.ts b/frontend-modern/src/features/docs/__tests__/configurationImportOutcomeDocs.test.ts
new file mode 100644
index 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),
+ );
+ }
+ });
+});