immich-app/immich · error · BadRequestException

Invalid backup name!

Error message

Invalid backup name!

What it means

`uploadBackup` takes the basename of the uploaded file and validates it against isValidDatabaseBackupName() before writing it into the backups folder. Files whose names don't match the expected backup filename pattern are rejected with this BadRequestException to prevent arbitrary files being written.

Solutions

1. Rename the file to match the expected Immich backup name pattern (as produced by the built-in backup feature) before uploading.
2. Download an existing backup from the server to see the exact naming convention and mimic it.
3. Verify you are uploading the database backup file actually created by Immich, not an arbitrary SQL dump.

Example fix

// before
formData.append('file', new Blob([data]), 'dump.sql'); // invalid name → 400
// after
formData.append('file', new Blob([data]), 'immich-db-backup-20260915.sql.gz'); // matches valid pattern

// Validate the filename against the backup pattern before upload
const pattern = /^immich-db-backup-.+$/; // match server's isValidDatabaseBackupName
if (!pattern.test(basename(file.name))) {
  file = new File([buffer], `immich-db-backup-${file.name}`, { type: file.type });
}

When it happens

Trigger: Uploading a database backup via POST /api/backups with a file whose originalname doesn't match the immich backup naming pattern (e.g. 'dump.sql', 'my backup.gz', or a name with path components).

Common situations: Renaming a pg_dump output before upload; uploading a plain SQL dump instead of the Immich-generated backup file; browser altering the filename; attempting to upload a non-backup file through the endpoint.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Quota has been exceeded!
• Unable to process profile image
• Unsupported file type
• Asset does not have valid dimensions
• Asset not found

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/9e5a44a68f9049a7. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/database-backup.service.ts:274

      this.logger.error(`Database Backup Failure: ${error}`);
      pgdump?.destroy();
      gzip?.destroy();
      await this.storageRepository
        .unlink(temporaryFilePath)

        .catch((error) => this.logger.error(`Failed to delete failed backup file: ${error}`));
      throw error;
    }

    this.logger.log(`Database Backup Success`);
    return backupFilePath;
  }

  async uploadBackup(file: Express.Multer.File): Promise<void> {
    const backupsFolder = StorageCore.getBaseFolder(StorageFolder.Backups);
    const fn = basename(file.originalname);
    if (!isValidDatabaseBackupName(fn)) {
      throw new BadRequestException('Invalid backup name!');
    }

    const filePath = path.join(backupsFolder, `uploaded-${fn}`);
    await this.storageRepository.createOrOverwriteFile(filePath, file.buffer);
  }

  downloadBackup(fileName: string): ImmichFileResponse {
    if (!isValidDatabaseBackupName(fileName)) {
      throw new BadRequestException('Invalid backup name!');
    }

    const filePath = path.join(StorageCore.getBaseFolder(StorageFolder.Backups), fileName);

    return {
      path: filePath,
      fileName,
      cacheControl: CacheControl.PrivateWithoutCache,
      contentType: fileName.endsWith('.gz') ? 'application/gzip' : 'application/sql',

View on GitHub (pinned to e55ac299a4)