Budibase/budibase · error

Backup incomplete - cannot download.

Error message

Backup incomplete - cannot download.

What it means

Downloading a workspace backup requires the backup object to exist in object storage, identified by metadata.filename. When the backup metadata document exists but has no filename (the backup never finished uploading), getBackupDownloadStream throws this error because there is nothing stored to stream. It guards against serving empty/corrupt downloads for incomplete backups.

Source

Thrown at packages/pro/src/sdk/backups/backup.ts:166

      }
    }
    page = expiredBackups.nextPage
  } while (page)

  return result
}

async function fetchWorkspaceBackups(
  workspaceId: string,
  opts?: BackupFetchOpts
) {
  return backups.fetchWorkspaceBackups(workspaceId, opts)
}

async function getBackupDownloadStream(backupId: string) {
  const metadata = await backups.getWorkspaceBackupMetadata(backupId)
  if (!metadata.filename) {
    throw new Error("Backup incomplete - cannot download.")
  }
  const { stream } = await objectStore.getReadStream(
    objectStore.ObjectStoreBuckets.BACKUPS,
    metadata.filename
  )
  return { metadata, stream }
}

async function downloadWorkspaceBackup(backupId: string): Promise<string> {
  const { stream } = await getBackupDownloadStream(backupId)
  const path = join(objectStore.budibaseTempDir(), utils.newid())
  const writeStream = fs.createWriteStream(path)
  return new Promise((resolve, reject) => {
    stream.on("error", reject)
    writeStream.on("error", reject)
    stream.pipe(writeStream).on("close", () => resolve(path))
  })
}

View on GitHub (pinned to a81a902e9a)

Solutions

1. Verify the backup completed (check metadata status / timestamps) and re-run the backup to produce a complete file.
2. Check that the BACKUPS bucket in the object store (MinIO/S3) is reachable and contains the file; fix storage connectivity if the upload failed.
3. Delete the incomplete backup record and create a new one instead of retrying the download.
4. If uploads are repeatedly failing, inspect worker logs at backup time for object-store errors and retry with sufficient disk/network.

Example fix

// before
const { stream } = await getBackupDownloadStream(backupId)
// after
const metadata = await backups.getWorkspaceBackupMetadata(backupId)
if (!metadata.filename) {
  throw new Error("Backup incomplete; please create a new backup")
}
const { stream } = await getBackupDownloadStream(backupId)

const metadata = await backups.getWorkspaceBackupMetadata(backupId)
if (!metadata.filename) {
  throw new Error(`Backup ${backupId} is incomplete; create a new backup`)
}

function isDownloadable(m: { filename?: string }): m is { filename: string } {
  return typeof m.filename === "string" && m.filename.length > 0
}

try {
  const { stream } = await getBackupDownloadStream(backupId)
} catch (err) {
  if (err.message === "Backup incomplete - cannot download.") {
    // prompt user to re-run the backup
  } else throw err
}

When it happens

Trigger: Calling getBackupDownloadStream(backupId) where backups.getWorkspaceBackupMetadata(backupId) returns a metadata doc whose filename field is undefined/empty — typically because the backup creation job failed or was interrupted after the metadata doc was written but before the file was uploaded to the BACKUPS bucket.

Common situations: Backup process crashed or the worker restarted mid-upload; object store (MinIO/S3) was unavailable during backup; user clicks download for a backup still in progress or listed in the UI despite a failed upload.

Related errors

• Invalid object store key: path traversal is not allowed.
• Access denied to object store bucket.${err}
• Stream to upload is invalid/undefined
• Unable to retrieve object
• Unable to retrieve stream - invalid response

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/9d1da9bde82f8037. Report an issue: GitHub.