{"record":{"id":"953317675971e60c","repo":"strapi/strapi","slug":"restore-failed-error","errorCode":null,"errorMessage":"restore failed ${error}","messagePattern":"restore failed (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/data-transfer/src/strapi/providers/local-destination/index.ts","lineNumber":193,"sourceCode":"\n    this.options.onTransferPhase?.('Local: preparing destination for restore…');\n\n    await this.transaction?.attach(async (trx) => {\n      try {\n        if (this.options.strategy === 'restore') {\n          if (this.#areAssetsIncluded()) {\n            this.options.onTransferPhase?.('Local: backing up existing upload folder…');\n          }\n          await this.#handleAssetsBackup();\n          if (this.#areAssetsIncluded()) {\n            this.options.onTransferPhase?.('Local: deleting existing media files from disk…');\n          }\n          await this.#deleteAllAssets(trx);\n          this.options.onTransferPhase?.('Local: clearing database content for restore…');\n          await this.#deleteFromRestoreOptions();\n        }\n      } catch (error) {\n        throw new Error(`restore failed ${error}`);\n      }\n    });\n  }\n\n  getMetadata(): IMetadata {\n    this.#reportInfo('getting metadata');\n    assertValidStrapi(this.strapi, 'Not able to get Schemas');\n    const strapiVersion = this.strapi.config.get<string>('info.strapi');\n    const createdAt = new Date().toISOString();\n\n    return {\n      createdAt,\n      strapi: {\n        version: strapiVersion,\n      },\n    };\n  }\n","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/strapi/strapi/blob/4a4101264d7098754df36e85fa629fd2f2349d8c/packages/core/data-transfer/src/strapi/providers/local-destination/index.ts#L175-L211","documentation":"Thrown by beforeTransfer() as a catch-all wrapper around the restore preparation steps: #handleAssetsBackup(), #deleteAllAssets(trx), and #deleteFromRestoreOptions(). The original error is stringified into the message. It runs inside a transaction.attach() callback, so the transaction will be rolled back by the engine on failure. The inner error could be a file-system failure, a database error, or a missing-options error.","triggerScenarios":"Any failure during the restore preparation phase: the uploads directory lacks write permissions (assets backup fails), a database query in deleteMany fails, the upload provider's delete() throws for a file, or #deleteFromRestoreOptions hits a missing restore option.","commonSituations":"Insufficient filesystem permissions on the public/uploads directory. A corrupt or locked database row during deleteMany. A custom upload provider whose delete() throws on missing files. Disk full during the backup move operation.","solutions":["Inspect the inner error (the part after 'restore failed ') to identify which sub-step failed.","For filesystem errors, check write permissions on strapi.dirs.static.public and the uploads subdirectory.","For database errors, check database connectivity, locks, and constraints.","For upload-provider errors, verify the upload provider configuration and that referenced files exist.","Re-run the transfer after fixing the root cause; the transaction rollback ensures the database is in a consistent pre-transfer state."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await provider.beforeTransfer();\n} catch (e) {\n  const msg = e instanceof Error ? e.message : String(e);\n  if (msg.startsWith('restore failed ')) {\n    const inner = msg.slice('restore failed '.length);\n    console.error('Restore preparation failed. Root cause:', inner);\n    // The transaction is rolled back; the DB is in its pre-transfer state.\n  } else {\n    throw e;\n  }\n}","preventionTips":["Pre-flight check: verify filesystem permissions on public/uploads before starting.","Pre-flight check: verify database connectivity.","Inspect the inner error string after 'restore failed ' to find the sub-step that failed.","The transaction rollback ensures consistency — safe to retry after fixing the root cause."],"tags":["data-transfer","restore","transaction","filesystem","database","wrapper-error"],"backgroundTag":null,"analyzedSha":"4a4101264d7098754df36e85fa629fd2f2349d8c","analyzedAt":"2026-08-12T12:47:50.760Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}