Skip to content

A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.

fix: resolves failed backup issue even when restic succeeds

towfiqif69ed189d293
diff --git a/backend/__tests__/jobs/JobProcessor.test.ts b/backend/__tests__/jobs/JobProcessor.test.ts
index 84bf926..2721fed 100644
--- a/backend/__tests__/jobs/JobProcessor.test.ts
+++ b/backend/__tests__/jobs/JobProcessor.test.ts
@@ -317,6 +317,78 @@ describe('JobProcessor', () => {
});
});
+ it('does not retry a non-retryable error and fails immediately', async () => {
+ const job: Job = {
+ id: 'job-1',
+ name: 'Backup',
+ payload: { planId: 'plan-1', backupId: 'backup-1' },
+ attempts: 0,
+ maxAttempts: 5,
+ retryDelay: 60000,
+ lastAttempt: 0,
+ };
+
+ // Error tagged as non-retryable (e.g. restic wrong-password exit code 12).
+ const nonRetryableError = Object.assign(new Error('wrong password'), {
+ code: 12,
+ retryable: false,
+ });
+
+ const backupTask = new MockTask('Backup', jest.fn());
+ backupTask.executeFunc.mockRejectedValueOnce(nonRetryableError);
+
+ mockJobQueueGetNext.mockReturnValueOnce(job).mockReturnValue(null);
+
+ const emitSpy = jest.spyOn(jobProcessor, 'emit');
+ jobProcessor.addTask(backupTask);
+
+ await processOneJob();
+
+ // Must NOT go through the retry path.
+ expect(mockJobQueueFailJob).not.toHaveBeenCalled();
+ // Job is cleared without re-queuing.
+ expect(mockJobQueueCompleteJob).toHaveBeenCalled();
+ // A warning is logged and a permanent failure is emitted immediately.
+ expect(mockLogger.warn).toHaveBeenCalledWith(
+ { module: 'JobProcessor', job: 'Backup' },
+ expect.stringContaining('non-retryable')
+ );
+ expect(emitSpy).toHaveBeenCalledWith('backup_failed', {
+ planId: 'plan-1',
+ backupId: 'backup-1',
+ error: 'wrong password',
+ });
+ });
+
+ it('still retries a retryable error (retryable !== false)', async () => {
+ const job: Job = {
+ id: 'job-1',
+ name: 'Backup',
+ payload: { planId: 'plan-1' },
+ attempts: 0,
+ maxAttempts: 5,
+ retryDelay: 60000,
+ lastAttempt: 0,
+ };
+
+ // Error tagged as retryable (e.g. restic lock-failed exit code 11).
+ const retryableError = Object.assign(new Error('unable to lock repository'), {
+ code: 11,
+ retryable: true,
+ });
+
+ const backupTask = new MockTask('Backup', jest.fn());
+ backupTask.executeFunc.mockRejectedValueOnce(retryableError);
+ mockJobQueueFailJob.mockReturnValueOnce(false);
+
+ mockJobQueueGetNext.mockReturnValueOnce(job).mockReturnValue(null);
+ jobProcessor.addTask(backupTask);
+
+ await processOneJob();
+
+ expect(mockJobQueueFailJob).toHaveBeenCalledWith(job);
+ });
+
it('delays retry based on retryDelay', async () => {
const job: Job = {
id: 'job-1',
diff --git a/backend/__tests__/managers/handlers/BackupHandler.test.ts b/backend/__tests__/managers/handlers/BackupHandler.test.ts
index 6ef7a81..49800f2 100644
--- a/backend/__tests__/managers/handlers/BackupHandler.test.ts
+++ b/backend/__tests__/managers/handlers/BackupHandler.test.ts
@@ -263,6 +263,115 @@ describe('BackupHandler', () => {
expect(mockMarkCompleted).toHaveBeenCalledWith('plan-1', 'backup-1', true);
});
+ it('should log a BACKUP_WARNING and complete successfully when backup exits with code 3', async () => {
+ // Dry run + unlock resolve normally; the actual backup invokes onComplete(3)
+ // (partial read - snapshot still created).
+ mockRunResticCommand.mockImplementation(
+ (args: string[], _env: any, onProgress: any, _onError: any, onComplete: any) => {
+ const isBackup = args[0] === 'backup' && !args.includes('--dry-run');
+ if (isBackup) {
+ // Emit a restic JSON error item so the warning message includes it.
+ onProgress?.(
+ Buffer.from(
+ JSON.stringify({
+ message_type: 'error',
+ error: { message: 'permission denied' },
+ item: '/data/locked.db',
+ })
+ )
+ );
+ onComplete?.(3);
+ }
+ return Promise.resolve('{"message_type":"summary"}');
+ }
+ );
+
+ const result = await handler.execute('plan-1', 'backup-1', baseOptions, {
+ attempts: 0,
+ maxAttempts: 5,
+ });
+
+ expect(result).toBeDefined();
+ // A BACKUP_WARNING action is logged in the progress tracking.
+ expect(mockUpdateAction).toHaveBeenCalledWith(
+ 'plan-1',
+ 'backup-1',
+ 'backup',
+ 'BACKUP_WARNING',
+ true,
+ expect.stringContaining('/data/locked.db: permission denied')
+ );
+ // The backup is still marked as completed (success), NOT failed/retried.
+ expect(mockMarkCompleted).toHaveBeenCalledWith('plan-1', 'backup-1', true);
+ });
+
+ it('should permanently fail (no retry) when backup exits with a non-retryable code', async () => {
+ // Dry run + unlock resolve; the actual backup rejects with wrong-password (12).
+ mockRunResticCommand.mockImplementation((args: string[]) => {
+ const isBackup = args[0] === 'backup' && !args.includes('--dry-run');
+ if (isBackup) {
+ return Promise.reject(Object.assign(new Error('wrong password'), { code: 12 }));
+ }
+ return Promise.resolve('{"message_type":"summary"}');
+ });
+
+ // Even though attempts (0) are far below maxAttempts (5), a non-retryable
+ // error must fail permanently on the first attempt.
+ await expect(
+ handler.execute('plan-1', 'backup-1', baseOptions, { attempts: 0, maxAttempts: 5 })
+ ).rejects.toMatchObject({ code: 12, retryable: false });
+
+ // markCompleted's final arg (permanentlyFailed) must be true.
+ expect(mockMarkCompleted).toHaveBeenCalledWith(
+ 'plan-1',
+ 'backup-1',
+ false,
+ expect.stringContaining('wrong password'),
+ true
+ );
+ // A retry must NOT be scheduled.
+ expect(mockUpdateAction).not.toHaveBeenCalledWith(
+ 'plan-1',
+ 'backup-1',
+ 'retry',
+ expect.stringContaining('BACKUP_RETRY'),
+ false,
+ undefined
+ );
+ });
+
+ it('should schedule a retry when backup exits with a retryable code', async () => {
+ // The actual backup rejects with lock-failed (11) - transient, should retry.
+ mockRunResticCommand.mockImplementation((args: string[]) => {
+ const isBackup = args[0] === 'backup' && !args.includes('--dry-run');
+ if (isBackup) {
+ return Promise.reject(Object.assign(new Error('unable to lock repository'), { code: 11 }));
+ }
+ return Promise.resolve('{"message_type":"summary"}');
+ });
+
+ await expect(
+ handler.execute('plan-1', 'backup-1', baseOptions, { attempts: 0, maxAttempts: 5 })
+ ).rejects.toMatchObject({ code: 11, retryable: true });
+
+ // Not permanently failed (final arg false), and a retry is scheduled.
+ expect(mockMarkCompleted).toHaveBeenCalledWith(
+ 'plan-1',
+ 'backup-1',
+ false,
+ expect.stringContaining('unable to lock repository'),
+ false
+ );
+ expect(mockUpdateAction).toHaveBeenCalledWith(
+ 'plan-1',
+ 'backup-1',
+ 'retry',
+ 'BACKUP_RETRY_1_OF_5_SCHEDULED',
+ false,
+ undefined
+ );
+ });
+
it('should prevent concurrent backups for same plan', async () => {
// Make the check deterministic by pre-populating the runningBackups set
handler['runningBackups'].add('plan-1');
diff --git a/backend/__tests__/utils/restic/exitCodes.test.ts b/backend/__tests__/utils/restic/exitCodes.test.ts
new file mode 100644
index 0000000..23e88ad
--- /dev/null
+++ b/backend/__tests__/utils/restic/exitCodes.test.ts
@@ -0,0 +1,97 @@
+import {
+ ResticExitCode,
+ classifyResticExitCode,
+ isResticBackupWarning,
+ isRetryableResticError,
+ isNonRetryableResticError,
+} from '../../../src/utils/restic/exitCodes';
+
+describe('classifyResticExitCode', () => {
+ it('classifies exit code 0 as success (not retryable, not a warning)', () => {
+ const result = classifyResticExitCode(0);
+ expect(result.category).toBe('success');
+ expect(result.retryable).toBe(false);
+ expect(result.isWarning).toBe(false);
+ });
+
+ it('classifies exit code 3 as a success-with-warning that must NOT be retried', () => {
+ const result = classifyResticExitCode(ResticExitCode.IncompleteBackup);
+ expect(result.category).toBe('warning');
+ expect(result.retryable).toBe(false);
+ expect(result.isWarning).toBe(true);
+ });
+
+ it('classifies exit code 11 (lock failed) as retryable', () => {
+ const result = classifyResticExitCode(ResticExitCode.RepositoryLockFailed);
+ expect(result.category).toBe('retryable');
+ expect(result.retryable).toBe(true);
+ });
+
+ it('classifies exit code 12 (wrong password) as fatal / not retryable', () => {
+ const result = classifyResticExitCode(ResticExitCode.WrongPassword);
+ expect(result.category).toBe('fatal');
+ expect(result.retryable).toBe(false);
+ });
+
+ it('classifies exit code 10 (repo does not exist) as fatal / not retryable', () => {
+ const result = classifyResticExitCode(ResticExitCode.RepositoryDoesNotExist);
+ expect(result.category).toBe('fatal');
+ expect(result.retryable).toBe(false);
+ });
+
+ it('classifies generic error (1) and runtime error (2) as retryable', () => {
+ expect(classifyResticExitCode(1).retryable).toBe(true);
+ expect(classifyResticExitCode(2).retryable).toBe(true);
+ });
+
+ it('classifies interruption (130) as cancelled / not retryable', () => {
+ const result = classifyResticExitCode(ResticExitCode.Interrupted);
+ expect(result.category).toBe('cancelled');
+ expect(result.retryable).toBe(false);
+ });
+
+ it('treats unknown or undefined codes as retryable by default', () => {
+ expect(classifyResticExitCode(undefined).retryable).toBe(true);
+ expect(classifyResticExitCode(999).retryable).toBe(true);
+ });
+});
+
+describe('isResticBackupWarning', () => {
+ it('returns true only for exit code 3', () => {
+ expect(isResticBackupWarning(3)).toBe(true);
+ expect(isResticBackupWarning(0)).toBe(false);
+ expect(isResticBackupWarning(11)).toBe(false);
+ expect(isResticBackupWarning(undefined)).toBe(false);
+ });
+});
+
+describe('isRetryableResticError', () => {
+ it('returns true for transient failures (1, 2, 11)', () => {
+ expect(isRetryableResticError(1)).toBe(true);
+ expect(isRetryableResticError(2)).toBe(true);
+ expect(isRetryableResticError(11)).toBe(true);
+ });
+
+ it('returns false for permanent failures and warnings (3, 10, 12, 130)', () => {
+ expect(isRetryableResticError(3)).toBe(false);
+ expect(isRetryableResticError(10)).toBe(false);
+ expect(isRetryableResticError(12)).toBe(false);
+ expect(isRetryableResticError(130)).toBe(false);
+ });
+});
+
+describe('isNonRetryableResticError', () => {
+ it('is true only for genuine permanent failures', () => {
+ expect(isNonRetryableResticError(12)).toBe(true);
+ expect(isNonRetryableResticError(10)).toBe(true);
+ expect(isNonRetryableResticError(130)).toBe(true);
+ });
+
+ it('is false for success, warning, retryable and unknown codes', () => {
+ expect(isNonRetryableResticError(0)).toBe(false);
+ expect(isNonRetryableResticError(3)).toBe(false); // warning is not a failure
+ expect(isNonRetryableResticError(11)).toBe(false);
+ expect(isNonRetryableResticError(1)).toBe(false);
+ expect(isNonRetryableResticError(undefined)).toBe(false);
+ });
+});
diff --git a/backend/__tests__/utils/restic/restic.test.ts b/backend/__tests__/utils/restic/restic.test.ts
index 52bc1b0..c696251 100644
--- a/backend/__tests__/utils/restic/restic.test.ts
+++ b/backend/__tests__/utils/restic/restic.test.ts
@@ -147,6 +147,45 @@ describe('runResticCommand', () => {
expect(onError).toHaveBeenCalledWith(expect.any(Buffer));
});
+ it('should resolve (not reject) when a backup exits with code 3 (partial read)', async () => {
+ const onComplete = jest.fn();
+ const summary = JSON.stringify({ message_type: 'summary', total_files_processed: 5 });
+
+ const promise = runResticCommand(['backup', '/test'], {}, undefined, undefined, onComplete);
+
+ setImmediate(() => {
+ mockProcess.stdout.emit('data', Buffer.from(summary));
+ mockProcess.stderr.emit('data', Buffer.from('error: could not read /test/locked.db'));
+ mockProcess.emit('close', 3);
+ });
+
+ await expect(promise).resolves.toBe(summary);
+ // onComplete still receives the real exit code so callers can log the warning.
+ expect(onComplete).toHaveBeenCalledWith(3);
+ });
+
+ it('should still reject with code 3 for a non-backup command', async () => {
+ const promise = runResticCommand(['check', '/test']);
+
+ setImmediate(() => {
+ mockProcess.stderr.emit('data', Buffer.from('some check error'));
+ mockProcess.emit('close', 3);
+ });
+
+ await expect(promise).rejects.toMatchObject({ code: 3 });
+ });
+
+ it('should attach the exit code to the rejected error', async () => {
+ const promise = runResticCommand(['backup', '/test']);
+
+ setImmediate(() => {
+ mockProcess.stderr.emit('data', Buffer.from('wrong password'));
+ mockProcess.emit('close', 12);
+ });
+
+ await expect(promise).rejects.toMatchObject({ code: 12 });
+ });
+
it('should call onComplete callback with exit code', async () => {
const onComplete = jest.fn();
diff --git a/backend/src/jobs/JobProcessor.ts b/backend/src/jobs/JobProcessor.ts
index aa68cd4..ddc77d0 100644
--- a/backend/src/jobs/JobProcessor.ts
+++ b/backend/src/jobs/JobProcessor.ts
@@ -198,9 +198,22 @@ class JobProcessor extends EventEmitter {
`Job failed during execution. Attempt ${job.attempts + 1} of ${job.maxAttempts}.`
);
- // failJob() will re-queue the job if there are attempts left,
- // and return 'true' only if it has permanently failed.
- const isPermanentlyFailed = jobQueue.failJob(job);
+ // Some failures are permanent and must not be retried (e.g. a restic
+ // backup that failed with a wrong password or a missing repository).
+ const isNonRetryable = (error as { retryable?: boolean })?.retryable === false;
+
+ let isPermanentlyFailed: boolean;
+ if (isNonRetryable) {
+ logger.warn(
+ { module: 'JobProcessor', job: job.name },
+ `Job failed with a non-retryable error. Skipping remaining retries.`
+ );
+ // Clear the running job without re-queuing it.
+ jobQueue.completeJob();
+ isPermanentlyFailed = true;
+ } else {
+ isPermanentlyFailed = jobQueue.failJob(job);
+ }
if (isPermanentlyFailed) {
logger.error(
diff --git a/backend/src/managers/handlers/BackupHandler.ts b/backend/src/managers/handlers/BackupHandler.ts
index 3198fd3..f70c15a 100644
--- a/backend/src/managers/handlers/BackupHandler.ts
+++ b/backend/src/managers/handlers/BackupHandler.ts
@@ -1,8 +1,13 @@
import os from 'os';
import fs from 'fs';
import { EventEmitter } from 'events';
-import { getBackupPlanStats, runResticCommand } from '../../utils/restic/restic';
+import {
+ getBackupPlanStats,
+ runResticCommand,
+ ResticCommandError,
+} from '../../utils/restic/restic';
import { generateResticRepoPath } from '../../utils/restic/helpers';
+import { classifyResticExitCode, isResticBackupWarning } from '../../utils/restic/exitCodes';
import { processManager } from '../ProcessManager';
import { PruneHandler } from './PruneHandler';
import { ProgressManager } from '../ProgressManager';
@@ -150,7 +155,13 @@ export class BackupHandler {
// If this is not the final attempt, log that a retry will be scheduled.
// const isFinalAttempt = retryInfo.attempts + 1 === retryInfo.maxAttempts;
- const permanentlyFailed = retryInfo.attempts + 1 > retryInfo.maxAttempts;
+ // If restic fails with code 10 or 12, retry cannot fix them, so fail immediately
+ const resticExitCode = (error as ResticCommandError)?.code;
+ const classification = classifyResticExitCode(resticExitCode);
+ const isNonRetryable = resticExitCode !== undefined && !classification.retryable;
+
+ const attemptsExhausted = retryInfo.attempts + 1 > retryInfo.maxAttempts;
+ const permanentlyFailed = attemptsExhausted || isNonRetryable;
// Mark as failed
await this.progressManager.markCompleted(
@@ -199,7 +210,12 @@ export class BackupHandler {
}
// Re-throw the error so the JobProcessor's catch block is triggered and decides whether to retry.
- throw new Error(errorMessage);
+ // Preserve the restic exit code and a `retryable` flag so the JobProcessor
+ // can skip retries for permanent failures
+ const rethrown: ResticCommandError & { retryable?: boolean } = new Error(errorMessage);
+ rethrown.code = resticExitCode;
+ rethrown.retryable = !isNonRetryable;
+ throw rethrown;
} finally {
// This block runs regardless of success or failure, ensuring we always clean up.
this.runningBackups.delete(planId);
@@ -282,11 +298,26 @@ export class BackupHandler {
await this.updateProgress(planId, backupId, 'backup', 'BACKUP_OPERATION_START', false);
const repoPassword = options.settings.encryption ? configService.config.ENCRYPTION_KEY : '';
- const handlers = this.createHandlers(planId, backupId);
+ const baseHandlers = this.createHandlers(planId, backupId);
const { resticArgs, resticEnv } = resticArgsAndEnv;
const resticArgsWithBackupTag: string[] = [...resticArgs, '--tag', `backup-${backupId}`];
const ignoreErrors = runConfig?.ignoreErrors || false;
+ // Capture restic exit code and warnings
+ let backupExitCode = 0;
+ const warnings: string[] = [];
+ const handlers = {
+ onProgress: (data: Buffer) => {
+ this.collectBackupWarnings(data, warnings);
+ baseHandlers.onProgress(data);
+ },
+ onError: baseHandlers.onError,
+ onComplete: (code: number) => {
+ backupExitCode = code;
+ baseHandlers.onComplete(code);
+ },
+ };
+
try {
// Run the Restic Backup command.
const result = await runResticCommand(
@@ -298,6 +329,18 @@ export class BackupHandler {
process => processManager.trackProcess('backup-' + backupId, process)
);
if (!this.cancelledBackups.has(planId + backupId)) {
+ // Exit code 3: snapshot created with warnings. Log this as a warning
+ // in the progress tracking rather than failing/retrying the backup.
+ if (isResticBackupWarning(backupExitCode)) {
+ await this.updateProgress(
+ planId,
+ backupId,
+ 'backup',
+ 'BACKUP_WARNING',
+ true,
+ this.buildBackupWarningMessage(warnings)
+ );
+ }
await this.updateProgress(planId, backupId, 'backup', 'BACKUP_OPERATION_COMPLETE', true);
}
return result;
@@ -626,6 +669,45 @@ export class BackupHandler {
};
}
+ /**
+ * Scans a chunk of restic `--json` output for `error` message items and
+ * accumulates their messages. Used to build the BACKUP_WARNING detail.
+ */
+ protected collectBackupWarnings(data: Buffer, warnings: string[]): void {
+ // Cap the number of collected warnings so this does not balloon the progress file
+ const MAX_WARNINGS = 100;
+ if (warnings.length >= MAX_WARNINGS) return;
+
+ const lines = data.toString().split('\n');
+ for (const line of lines) {
+ const trimmed = line.trim();
+ if (!trimmed) continue;
+ try {
+ const parsed = JSON.parse(trimmed);
+ if (parsed?.message_type === 'error') {
+ const item = parsed.item ? `${parsed.item}: ` : '';
+ const message = parsed.error?.message || parsed.error || 'Unknown read error';
+ warnings.push(`${item}${message}`);
+ if (warnings.length >= MAX_WARNINGS) return;
+ }
+ } catch {
+ // Ignore non-JSON lines.
+ }
+ }
+ }
+
+ /**
+ * Builds a nice warning message for a backup that completed with exit code 3
+ */
+ protected buildBackupWarningMessage(warnings: string[]): string {
+ const header =
+ 'Backup completed, but some files or directories could not be read and were skipped. The snapshot was still created.';
+ if (warnings.length === 0) {
+ return header;
+ }
+ return `${header}\n\n${warnings.join('\n')}`;
+ }
+
/**
* Helper to update restic progress with error handling
*/
@@ -717,7 +799,10 @@ export class BackupHandler {
false,
error?.message || 'Unknown Error'
);
- throw new Error(`Dry run failed: ${error.message}`);
+ // Preserve the restic exit code
+ const dryRunError: ResticCommandError = new Error(`Dry run failed: ${error.message}`);
+ dryRunError.code = (error as ResticCommandError)?.code;
+ throw dryRunError;
} else {
return dryRunSummary;
}
diff --git a/backend/src/utils/restic/exitCodes.ts b/backend/src/utils/restic/exitCodes.ts
new file mode 100644
index 0000000..a0f2dad
--- /dev/null
+++ b/backend/src/utils/restic/exitCodes.ts
@@ -0,0 +1,148 @@
+/**
+ * Classification of restic process exit codes so the backup pipeline can decide
+ * whether to retry, fail immediately, or treat the result as success-with-warning.
+ */
+
+export enum ResticExitCode {
+ Success = 0,
+ GenericError = 1,
+ GoRuntimeError = 2,
+ /** backup could not read some source files/dirs (snapshot still created). */
+ IncompleteBackup = 3,
+ RepositoryDoesNotExist = 10,
+ RepositoryLockFailed = 11,
+ WrongPassword = 12,
+ /** Interrupted via SIGINT/SIGTERM. */
+ Interrupted = 130,
+}
+
+export type ResticExitCategory = 'success' | 'warning' | 'retryable' | 'fatal' | 'cancelled';
+
+export interface ResticExitClassification {
+ code?: number;
+ category: ResticExitCategory;
+ retryable: boolean;
+ isWarning: boolean;
+ description: string;
+}
+
+interface ResticExitCodeMeta {
+ name: string;
+ category: ResticExitCategory;
+ retryable: boolean;
+ isWarning: boolean;
+ description: string;
+}
+
+// Codes 1 and 2 are treated as retryable because they most commonly stem from
+// transient conditions (network, storage, memory pressure).
+export const RESTIC_EXIT_CODES: Record<number, ResticExitCodeMeta> = {
+ [ResticExitCode.Success]: {
+ name: 'SUCCESS',
+ category: 'success',
+ retryable: false,
+ isWarning: false,
+ description: 'Command was successful.',
+ },
+ [ResticExitCode.GenericError]: {
+ name: 'GENERIC_ERROR',
+ category: 'retryable',
+ retryable: true,
+ isWarning: false,
+ description: 'Command failed with a generic error (often a transient network/storage issue).',
+ },
+ [ResticExitCode.GoRuntimeError]: {
+ name: 'GO_RUNTIME_ERROR',
+ category: 'retryable',
+ retryable: true,
+ isWarning: false,
+ description: 'Go runtime error (e.g. out of memory); usually transient.',
+ },
+ [ResticExitCode.IncompleteBackup]: {
+ name: 'INCOMPLETE_BACKUP',
+ category: 'warning',
+ retryable: false,
+ isWarning: true,
+ description:
+ 'Backup completed but some source files or directories could not be read. A snapshot was still created.',
+ },
+ [ResticExitCode.RepositoryDoesNotExist]: {
+ name: 'REPOSITORY_DOES_NOT_EXIST',
+ category: 'fatal',
+ retryable: false,
+ isWarning: false,
+ description:
+ 'The repository does not exist. This is a configuration issue that a retry cannot fix.',
+ },
+ [ResticExitCode.RepositoryLockFailed]: {
+ name: 'REPOSITORY_LOCK_FAILED',
+ category: 'retryable',
+ retryable: true,
+ isWarning: false,
+ description:
+ 'Failed to lock the repository (usually a stale or concurrent lock); retrying may succeed.',
+ },
+ [ResticExitCode.WrongPassword]: {
+ name: 'WRONG_PASSWORD',
+ category: 'fatal',
+ retryable: false,
+ isWarning: false,
+ description: 'Wrong password - the repository cannot be decrypted. A retry cannot fix this.',
+ },
+ [ResticExitCode.Interrupted]: {
+ name: 'INTERRUPTED',
+ category: 'cancelled',
+ retryable: false,
+ isWarning: false,
+ description: 'Restic was interrupted (SIGINT/SIGTERM).',
+ },
+};
+
+// Unknown/undefined codes default to retryable (transient failure).
+export function classifyResticExitCode(code?: number): ResticExitClassification {
+ if (code === undefined || code === null) {
+ return {
+ code,
+ category: 'retryable',
+ retryable: true,
+ isWarning: false,
+ description: 'Unknown error (no restic exit code available).',
+ };
+ }
+
+ const meta = RESTIC_EXIT_CODES[code];
+ if (!meta) {
+ return {
+ code,
+ category: 'retryable',
+ retryable: true,
+ isWarning: false,
+ description: `Unrecognized restic exit code ${code}.`,
+ };
+ }
+
+ return {
+ code,
+ category: meta.category,
+ retryable: meta.retryable,
+ isWarning: meta.isWarning,
+ description: meta.description,
+ };
+}
+
+export function isResticBackupWarning(code?: number): boolean {
+ return code === ResticExitCode.IncompleteBackup;
+}
+
+export function isRetryableResticError(code?: number): boolean {
+ return classifyResticExitCode(code).retryable;
+}
+
+export function isNonRetryableResticError(code?: number): boolean {
+ if (code === undefined || code === null) return false;
+ const classification = classifyResticExitCode(code);
+ return (
+ (classification.category === 'fatal' || classification.category === 'cancelled') &&
+ !classification.retryable
+ );
+}
diff --git a/backend/src/utils/restic/restic.ts b/backend/src/utils/restic/restic.ts
index c8b54bd..78c3904 100644
--- a/backend/src/utils/restic/restic.ts
+++ b/backend/src/utils/restic/restic.ts
@@ -10,6 +10,7 @@ import { configService } from '../../services/ConfigService';
import { buildResticEnvFromSettings, buildRcloneEnvFromSettings } from '../globalSettings';
import { BackupVerifiedResult } from '../../types/plans';
import { runHelper } from '../linuxHelper';
+import { ResticExitCode } from './exitCodes';
export type ResticCommandError = Error & {
code?: number;
@@ -165,7 +166,8 @@ export function runResticCommand(
// console.log('Restic Process exited with code:', code);
if (!wasCancelled) {
onComplete?.(code);
- if (code === 0) {
+ const isBackupWarning = cmd === 'backup' && code === ResticExitCode.IncompleteBackup;
+ if (code === 0 || isBackupWarning) {
let result = output.trim();
if (isStreamingDryRun) {
// Only the final summary line is meaningful for dry-runs.