Skip to content

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

fix: resolves various restore issues

towfiqi33368d0697b7
diff --git a/backend/__tests__/managers/BaseRestoreManager.test.ts b/backend/__tests__/managers/BaseRestoreManager.test.ts
index 116af40..9688f16 100644
--- a/backend/__tests__/managers/BaseRestoreManager.test.ts
+++ b/backend/__tests__/managers/BaseRestoreManager.test.ts
@@ -104,7 +104,7 @@ describe('BaseRestoreManager', () => {
expect(addPriorityJobSpy).toHaveBeenCalledWith(
'Restore',
- { backupId, restoreId: 'generated-restore-id', options },
+ { backupId, restoreId: 'generated-restore-id', planId: options.planId, options },
2,
60000
);
diff --git a/backend/__tests__/managers/handlers/RestoreHandler.test.ts b/backend/__tests__/managers/handlers/RestoreHandler.test.ts
index e98d73f..0e481a1 100644
--- a/backend/__tests__/managers/handlers/RestoreHandler.test.ts
+++ b/backend/__tests__/managers/handlers/RestoreHandler.test.ts
@@ -98,6 +98,7 @@ jest.mock('fs', () => ({
import { EventEmitter } from 'events';
import { RestoreHandler } from '../../../src/managers/handlers/RestoreHandler';
import os from 'os';
+import * as linuxHelper from '../../../src/utils/linuxHelper';
describe('RestoreHandler', () => {
let handler: RestoreHandler;
@@ -437,7 +438,7 @@ describe('RestoreHandler', () => {
it('should throw error when target path not writable', async () => {
jest.spyOn(os, 'freemem').mockReturnValue(1024 * 1024 * 1024);
jest.spyOn(os, 'cpus').mockReturnValue(new Array(4));
- mockAccess.mockRejectedValueOnce(new Error('Permission denied'));
+ jest.spyOn(linuxHelper, 'canWriteTargetOrParent').mockResolvedValueOnce(false);
await expect(handler.canRun(baseOptions)).rejects.toThrow('Target path not writable');
});
@@ -773,15 +774,6 @@ describe('RestoreHandler', () => {
handlers.onProgress(Buffer.from('progress data'));
expect(mockUpdateResticProgress).toHaveBeenCalledWith('plan-1', 'restore-1', 'progress data');
- // Test error handler
- handlers.onError(Buffer.from('Error message'));
- expect(errorListener).toHaveBeenCalledWith({
- backupId: 'backup-1',
- restoreId: 'restore-1',
- planId: 'plan-1',
- error: 'Error message',
- });
-
// Test complete handler
handlers.onComplete(0);
expect(completeListener).toHaveBeenCalledWith({
@@ -791,14 +783,12 @@ describe('RestoreHandler', () => {
success: true,
});
- // Test complete handler with failure
+ handlers.onError(Buffer.from('Error message'));
+
+ completeListener.mockClear();
handlers.onComplete(1);
- expect(completeListener).toHaveBeenCalledWith({
- backupId: 'backup-1',
- restoreId: 'restore-1',
- planId: 'plan-1',
- success: false,
- });
+ expect(completeListener).not.toHaveBeenCalled();
+ expect(errorListener).not.toHaveBeenCalled();
});
});
@@ -934,6 +924,44 @@ describe('RestoreHandler', () => {
'Restore failed'
);
});
+
+ it('should treat a metadata-only restic failure as success', async () => {
+ const completeListener = jest.fn();
+ emitter.on('restore_complete', completeListener);
+
+ const stderr = [
+ '{"message_type":"error","error":{"message":"failed to restore timestamp of \\"C:\\\\R\\\\C\\\\Users\\": Access is denied."},"during":"restore","item":"\\\\C\\\\Users"}',
+ '{"message_type":"exit_error","code":1,"message":"Fatal: There were 1 errors"}',
+ ].join('\n');
+ const resticError: any = new Error(stderr);
+ resticError.code = 1;
+ resticError.stderr = stderr;
+ mockRunResticCommand.mockRejectedValueOnce(resticError);
+
+ const result = await handler['executeRestorePhase'](
+ 'plan-1',
+ 'backup-1',
+ 'restore-1',
+ mockSnapshot,
+ baseOptions
+ );
+
+ expect(result).toBe('');
+ expect(completeListener).toHaveBeenCalledWith({
+ planId: 'plan-1',
+ backupId: 'backup-1',
+ restoreId: 'restore-1',
+ success: true,
+ });
+ expect(mockUpdateAction).toHaveBeenCalledWith(
+ 'plan-1',
+ 'restore-1',
+ 'restore',
+ 'RESTORE_OPERATION_COMPLETE',
+ true,
+ 'Restore completed but some file metadata (timestamps, ownership or permissions) could not be applied.'
+ );
+ });
});
describe('preRestorePhase', () => {
diff --git a/backend/__tests__/utils/restic/exitCodes.test.ts b/backend/__tests__/utils/restic/exitCodes.test.ts
index 23e88ad..10b0134 100644
--- a/backend/__tests__/utils/restic/exitCodes.test.ts
+++ b/backend/__tests__/utils/restic/exitCodes.test.ts
@@ -4,8 +4,48 @@ import {
isResticBackupWarning,
isRetryableResticError,
isNonRetryableResticError,
+ isMetadataOnlyRestoreFailure,
} from '../../../src/utils/restic/exitCodes';
+describe('isMetadataOnlyRestoreFailure', () => {
+ const timestampError =
+ '{"message_type":"error","error":{"message":"failed to restore timestamp of \\"C:\\\\\\\\R\\\\\\\\C\\\\\\\\Users\\": Access is denied."},"during":"restore","item":"\\\\C\\\\Users"}';
+ const fileError =
+ '{"message_type":"error","error":{"message":"open C:\\\\R\\\\disk.vhdx: There is not enough space on the disk."},"during":"restore","item":"\\\\disk.vhdx"}';
+ const exitError = '{"message_type":"exit_error","code":1,"message":"Fatal: There were 1 errors"}';
+
+ it('returns true when every error is a metadata error', () => {
+ expect(isMetadataOnlyRestoreFailure(1, `${timestampError}\n${exitError}`)).toBe(true);
+ });
+
+ it('returns true for the multi-line Windows metadata error', () => {
+ const windowsError =
+ '{"message_type":"error","error":{"message":"error restoring creation time for: C:\\\\R\\\\C\\\\Users : Access is denied.\\nerror restoring file attributes for: C:\\\\R\\\\C\\\\Users : Access is denied."},"during":"restore","item":"\\\\C\\\\Users"}';
+ expect(isMetadataOnlyRestoreFailure(1, `${windowsError}\n${exitError}`)).toBe(true);
+ });
+
+ it('returns false when one line of a multi-line error is not metadata', () => {
+ const mixedError =
+ '{"message_type":"error","error":{"message":"error restoring creation time for: C:\\\\R\\\\C\\\\Users : Access is denied.\\nopen C:\\\\R\\\\disk.vhdx: Access is denied."},"during":"restore","item":"\\\\C\\\\Users"}';
+ expect(isMetadataOnlyRestoreFailure(1, `${mixedError}\n${exitError}`)).toBe(false);
+ });
+
+ it('returns false when a file error is also reported', () => {
+ expect(isMetadataOnlyRestoreFailure(1, `${timestampError}\n${fileError}\n${exitError}`)).toBe(false);
+ });
+
+ it('returns false for non-JSON output', () => {
+ expect(isMetadataOnlyRestoreFailure(1, `${timestampError}\nFatal: repository is locked`)).toBe(false);
+ });
+
+ it('returns false for other exit codes or no errors', () => {
+ expect(isMetadataOnlyRestoreFailure(3, `${timestampError}\n${exitError}`)).toBe(false);
+ expect(isMetadataOnlyRestoreFailure(undefined, timestampError)).toBe(false);
+ expect(isMetadataOnlyRestoreFailure(1, exitError)).toBe(false);
+ expect(isMetadataOnlyRestoreFailure(1, '')).toBe(false);
+ });
+});
+
describe('classifyResticExitCode', () => {
it('classifies exit code 0 as success (not retryable, not a warning)', () => {
const result = classifyResticExitCode(0);
diff --git a/backend/src/managers/BaseRestoreManager.ts b/backend/src/managers/BaseRestoreManager.ts
index 54d6225..14bd72d 100644
--- a/backend/src/managers/BaseRestoreManager.ts
+++ b/backend/src/managers/BaseRestoreManager.ts
@@ -34,7 +34,12 @@ export class BaseRestoreManager extends EventEmitter {
): Promise<{ success: boolean; result: string }> {
const restoreId = generateUID();
- jobQueue.addPriorityJob('Restore', { backupId, restoreId, options }, 2, 60 * 1000);
+ jobQueue.addPriorityJob(
+ 'Restore',
+ { backupId, restoreId, planId: options.planId, options },
+ 2,
+ 60 * 1000
+ );
return { success: true, result: 'Restore job has been added to the queue.' };
}
diff --git a/backend/src/managers/handlers/RestoreHandler.ts b/backend/src/managers/handlers/RestoreHandler.ts
index 3de3f5c..c414add 100644
--- a/backend/src/managers/handlers/RestoreHandler.ts
+++ b/backend/src/managers/handlers/RestoreHandler.ts
@@ -26,6 +26,8 @@ import {
runHelper,
} from '../../utils/linuxHelper';
import { checkDestinationSpace } from '../../utils/checkDestinationSpace';
+import { isMetadataOnlyRestoreFailure } from '../../utils/restic/exitCodes';
+import { planLogger } from '../../utils/logger';
export class RestoreHandler {
private runningRestores = new Set<string>();
@@ -127,7 +129,7 @@ export class RestoreHandler {
}
// --- 4. CENTRALIZED ERROR HANDLING ---
- const permanentlyFailed = retryInfo.attempts + 1 > retryInfo.maxAttempts;
+ const permanentlyFailed = retryInfo.attempts + 1 >= retryInfo.maxAttempts;
await this.progressManager.markCompleted(
planId,
@@ -148,7 +150,7 @@ export class RestoreHandler {
}
// Emit the 'error' event for the listener to log the attempt failure.
- this.emitter.emit('restore_error', {
+ this.emitter.emit(permanentlyFailed ? 'restore_failed' : 'restore_error', {
planId,
backupId,
restoreId,
@@ -289,20 +291,20 @@ export class RestoreHandler {
try {
const result = useHelper
? await runHelperRestore(
- helperArgs,
- handlers.onProgress,
- handlers.onError,
- handlers.onComplete,
- process => processManager.trackProcess(`restore-${restoreId}`, process)
- )
+ helperArgs,
+ handlers.onProgress,
+ handlers.onError,
+ handlers.onComplete,
+ process => processManager.trackProcess(`restore-${restoreId}`, process)
+ )
: await runResticCommand(
- resticOpts.args,
- resticOpts.env,
- handlers.onProgress,
- handlers.onError,
- handlers.onComplete,
- process => processManager.trackProcess(`restore-${restoreId}`, process)
- );
+ resticOpts.args,
+ resticOpts.env,
+ handlers.onProgress,
+ handlers.onError,
+ handlers.onComplete,
+ process => processManager.trackProcess(`restore-${restoreId}`, process)
+ );
await this.updateProgress(planId, restoreId, 'restore', 'RESTORE_OPERATION_COMPLETE', true);
return result;
} catch (error: any) {
@@ -340,9 +342,14 @@ export class RestoreHandler {
/xattr\.LSet.*operation not permitted/i.test(errMsg) &&
!/fatal(?!.*xattr)/i.test(errMsg);
- if (isXattrOnly) {
+ const isMetadataOnly = isMetadataOnlyRestoreFailure(
+ restoreError?.code,
+ restoreError?.stderr || errMsg
+ );
+
+ if (isXattrOnly || isMetadataOnly) {
console.warn(
- `[RestoreHandler] Restic reported xattr errors but file data was restored. Treating as success.`
+ `[RestoreHandler] Restic reported metadata errors but file data was restored. Treating as success.`
);
await this.updateProgress(
planId,
@@ -350,8 +357,11 @@ export class RestoreHandler {
'restore',
'RESTORE_OPERATION_COMPLETE',
true,
- 'Restore completed but some macOS extended attributes could not be set (SIP restriction).'
+ isXattrOnly
+ ? 'Restore completed but some macOS extended attributes could not be set (SIP restriction).'
+ : 'Restore completed but some file metadata (timestamps, ownership or permissions) could not be applied.'
);
+ this.emitter.emit('restore_complete', { backupId, restoreId, planId, success: true });
return '';
}
@@ -523,9 +533,7 @@ export class RestoreHandler {
}
}
} else if (options.target && options.target !== '/') {
- try {
- await access(path.dirname(options.target), constants.W_OK);
- } catch (error) {
+ if (!(await canWriteTargetOrParent(options.target))) {
throw new Error(`Target path not writable: ${options.target}`);
}
}
@@ -660,7 +668,8 @@ export class RestoreHandler {
private async validateHelperRestoreTarget(options: RestoreOptions): Promise<void> {
const target = options.target || '/';
- const allowRootTarget = target === '/' && ((options.includes?.length || 0) > 0 || (options.sources?.length || 0) > 0);
+ const allowRootTarget =
+ target === '/' && ((options.includes?.length || 0) > 0 || (options.sources?.length || 0) > 0);
if (isHelperDeniedTarget(target, allowRootTarget)) {
throw new Error(
`Restore target is not allowed for privileged restore: ${target}. Choose a non-system directory such as /srv/pluton-restore.`
@@ -715,19 +724,17 @@ export class RestoreHandler {
this.progressManager.updateResticProgress(planId, restoreId, progressLine);
},
onError: (data: Buffer) => {
- this.emitter.emit('restore_error', {
- backupId,
- restoreId,
- planId,
- error: data.toString(),
- });
+ // Only log here. execute() sends one final restore_error or restore_failed event with
+ // the same text, and a metadata-only failure still counts as a successful restore.
+ planLogger('restore', planId, backupId).error(data.toString());
},
onComplete: (code: number | null) => {
+ if (code !== 0) return;
this.emitter.emit('restore_complete', {
backupId,
restoreId,
planId,
- success: code === 0,
+ success: true,
});
},
};
diff --git a/backend/src/services/events/RestoreEventService.ts b/backend/src/services/events/RestoreEventService.ts
index a94eda1..9afd3f6 100644
--- a/backend/src/services/events/RestoreEventService.ts
+++ b/backend/src/services/events/RestoreEventService.ts
@@ -66,7 +66,16 @@ export class RestoreEventService {
}
// Create the restore entry in the Database
- const restore = await this.restoreStore.create(parsedRestoreData);
+ const existing = await this.restoreStore.getById(restoreId);
+ const restore = existing
+ ? await this.restoreStore.update(restoreId, {
+ status: 'started',
+ inProgress: true,
+ errorMsg: null,
+ ended: null,
+ taskStats: parsedRestoreData.taskStats,
+ })
+ : await this.restoreStore.create(parsedRestoreData);
if (!restore) {
throw new Error('Failed to create restore entry in the Database');
diff --git a/backend/src/services/listeners/RestoreEventListener.ts b/backend/src/services/listeners/RestoreEventListener.ts
index 7784548..7b21b35 100644
--- a/backend/src/services/listeners/RestoreEventListener.ts
+++ b/backend/src/services/listeners/RestoreEventListener.ts
@@ -28,8 +28,7 @@ export class RestoreEventListener {
this.onRestoreComplete(event)
);
this.localAgent.on('restore_error', (event: RestoreErrorEvent) => this.onRestoreError(event));
- this.localAgent.on('restore_failed', (event: RestoreErrorEvent) => this.onRestoreFailed(event));
- }
+ this.localAgent.on('restore_failed', (event: RestoreErrorEvent) => this.onRestoreFailed(event)); }
private async onRestoreStart(data: RestoreStartEvent) {
await this.restoreEventService.onRestoreStart(data);
diff --git a/backend/src/utils/linuxHelper.ts b/backend/src/utils/linuxHelper.ts
index 2daeda5..be37290 100644
--- a/backend/src/utils/linuxHelper.ts
+++ b/backend/src/utils/linuxHelper.ts
@@ -161,11 +161,18 @@ export async function canWriteTargetOrParent(target: string): Promise<boolean> {
}
}
- try {
- await access(path.dirname(normalized), constants.W_OK);
- return true;
- } catch {
- return false;
+ let current = path.dirname(normalized);
+ while (true) {
+ try {
+ await access(current, constants.W_OK);
+ return true;
+ } catch (error: any) {
+ const parent = path.dirname(current);
+ if (error?.code !== 'ENOENT' || parent === current) {
+ return false;
+ }
+ current = parent;
+ }
}
}
diff --git a/backend/src/utils/restic/exitCodes.ts b/backend/src/utils/restic/exitCodes.ts
index a0f2dad..4b032c9 100644
--- a/backend/src/utils/restic/exitCodes.ts
+++ b/backend/src/utils/restic/exitCodes.ts
@@ -134,6 +134,40 @@ export function isResticBackupWarning(code?: number): boolean {
return code === ResticExitCode.IncompleteBackup;
}
+const RESTORE_METADATA_ERROR_PATTERNS = [
+ /^failed to restore timestamp of /,
+ /^error restoring creation time for: /,
+ /^error restoring file attributes for: /,
+ /^error restoring security descriptor for: /,
+ /^(lchown|chmod) .*: (operation not permitted|permission denied)$/i,
+];
+
+// True when restic restore exited with code 1 and every reported error only failed to apply file metadata.
+export function isMetadataOnlyRestoreFailure(code: number | undefined, stderr: string): boolean {
+ if (code !== ResticExitCode.GenericError) return false;
+ const messages = stderr
+ .split(/\r?\n/)
+ .filter(line => line.trim())
+ .map(line => {
+ try {
+ return JSON.parse(line);
+ } catch {
+ return null;
+ }
+ });
+ if (messages.some(m => m?.message_type !== 'error' && m?.message_type !== 'exit_error')) {
+ return false;
+ }
+ const errorLines = messages
+ .filter(m => m.message_type === 'error')
+ .flatMap(m => String(m.error?.message || '').split(/\r?\n/))
+ .filter(line => line.trim());
+ return (
+ errorLines.length > 0 &&
+ errorLines.every(line => RESTORE_METADATA_ERROR_PATTERNS.some(p => p.test(line)))
+ );
+}
+
export function isRetryableResticError(code?: number): boolean {
return classifyResticExitCode(code).retryable;
}