What causes "backup.json.gz should present to restore" in hcengineering/platform?

Run a backup first so backup.json.gz is created in the target storage.

backup.json.gz should present to restore

Error message

backup.json.gz should present to restore

What it means

backupList reads the backup metadata file backup.json.gz from the storage to print workspace and snapshot info. If storage.exists('backup.json.gz') is false it throws this error, because no backup has been taken yet (or the metadata file was deleted), so there is nothing to list.

Source

Thrown at server/backup/src/utils.ts:71

  BlobData,
  DomainData,
  Snapshot,
  SnapshotV6
} from './types'
export * from './storage'

const dataBlobSize = 250 * 1024 * 1024

const defaultLevel = 9

/**
 * @public
 */
export async function backupList (storage: BackupStorage): Promise<void> {
  const infoFile = 'backup.json.gz'

  if (!(await storage.exists(infoFile))) {
    throw new Error(`${infoFile} should present to restore`)
  }
  const backupInfo: BackupInfo = JSON.parse(gunzipSync(new Uint8Array(await storage.loadFile(infoFile))).toString())
  console.log('workspace:', backupInfo.workspace ?? '', backupInfo.version)
  for (const s of backupInfo.snapshots) {
    console.log('snapshot: id:', s.date, ' date:', new Date(s.date))
  }
}

/**
 * @public
 */
export async function backupRemoveLast (storage: BackupStorage, date: number): Promise<void> {
  const infoFile = 'backup.json.gz'

  if (!(await storage.exists(infoFile))) {
    throw new Error(`${infoFile} should present to restore`)
  }
  const backupInfo: BackupInfo = JSON.parse(gunzipSync(new Uint8Array(await storage.loadFile(infoFile))).toString())

View on GitHub (pinned to 63e28dc964)

Solutions

Run a backup first so backup.json.gz is created in the target storage.
Verify storage config: bucket name, prefix/path, region, and credentials point to the location that actually holds backups.
Check the file exists: storage.exists('backup.json.gz') or `aws s3 ls s3://bucket/prefix/backup.json.gz`.
If the file was deleted, restore it from another replica or re-create backups from the source workspace.

Example fix

// before
await backupList(storage) // throws if metadata missing

// after
if (!(await storage.exists('backup.json.gz'))) {
  console.error('No backup metadata found; run backup first')
} else {
  await backupList(storage)
}

Defensive patterns

Strategy: validation

Validate before calling

if (!(await storage.exists('backup.json.gz'))) {
  throw new Error('backup.json.gz missing: run backup first or fix storage config')
}
await backupList(storage)

Try / catch

try {
  await backupList(storage)
} catch (err) {
  if (err.message.includes('should present to restore')) {
    console.error('No backup metadata in storage — verify bucket/prefix and run a backup first')
    return
  }
  throw err
}

Prevention

Check storage.exists('backup.json.gz') before any backup tooling call.
Pin and verify storage config (bucket, prefix, region, credentials) per environment.
Ensure the backup job runs and succeeds before scheduling list/restore/size operations.
Alert on missing backup.json.gz so silent backup pipeline failures are caught early.

When it happens

Trigger: Calling backupList(storage) against a storage (S3 bucket, local dir) where no backup has ever run, a wrong bucket/prefix was configured, or backup.json.gz was manually removed.

Common situations: Pointing the tool at an empty/new S3 prefix, mistyped credentials or region resolving to a different bucket, running restore-side tooling before the first backup job, or a failed first backup that never wrote the metadata file.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/f29f599ceb481005. Report an issue: GitHub.