{"record":{"id":"f29f599ceb481005","repo":"hcengineering/platform","slug":"backup-json-gz-should-present-to-restore","errorCode":null,"errorMessage":"backup.json.gz should present to restore","messagePattern":"backup\\.json\\.gz should present to restore","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/backup/src/utils.ts","lineNumber":71,"sourceCode":"  BlobData,\n  DomainData,\n  Snapshot,\n  SnapshotV6\n} from './types'\nexport * from './storage'\n\nconst dataBlobSize = 250 * 1024 * 1024\n\nconst defaultLevel = 9\n\n/**\n * @public\n */\nexport async function backupList (storage: BackupStorage): Promise<void> {\n  const infoFile = 'backup.json.gz'\n\n  if (!(await storage.exists(infoFile))) {\n    throw new Error(`${infoFile} should present to restore`)\n  }\n  const backupInfo: BackupInfo = JSON.parse(gunzipSync(new Uint8Array(await storage.loadFile(infoFile))).toString())\n  console.log('workspace:', backupInfo.workspace ?? '', backupInfo.version)\n  for (const s of backupInfo.snapshots) {\n    console.log('snapshot: id:', s.date, ' date:', new Date(s.date))\n  }\n}\n\n/**\n * @public\n */\nexport async function backupRemoveLast (storage: BackupStorage, date: number): Promise<void> {\n  const infoFile = 'backup.json.gz'\n\n  if (!(await storage.exists(infoFile))) {\n    throw new Error(`${infoFile} should present to restore`)\n  }\n  const backupInfo: BackupInfo = JSON.parse(gunzipSync(new Uint8Array(await storage.loadFile(infoFile))).toString())","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/server/backup/src/utils.ts#L53-L89","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nawait backupList(storage) // throws if metadata missing\n\n// after\nif (!(await storage.exists('backup.json.gz'))) {\n  console.error('No backup metadata found; run backup first')\n} else {\n  await backupList(storage)\n}","handlingStrategy":"validation","validationCode":"if (!(await storage.exists('backup.json.gz'))) {\n  throw new Error('backup.json.gz missing: run backup first or fix storage config')\n}\nawait backupList(storage)","typeGuard":null,"tryCatchPattern":"try {\n  await backupList(storage)\n} catch (err) {\n  if (err.message.includes('should present to restore')) {\n    console.error('No backup metadata in storage — verify bucket/prefix and run a backup first')\n    return\n  }\n  throw err\n}","preventionTips":["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."],"tags":["backup","missing-file","storage"],"backgroundTag":"missing-backup-metadata","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}