strapi/strapi · error · ProviderInitializationError

File '${filePath}' is not a valid Strapi data file.

Error message

File '${filePath}' is not a valid Strapi data file.

What it means

ProviderInitializationError thrown in bootstrap() when #loadMetadata() throws AND encryption is disabled. The file could not be parsed as a Strapi data archive and, since no decryption was attempted, the message attributes the failure to the file itself being invalid.

Source

Thrown at packages/core/data-transfer/src/file/providers/source/index.ts:123

  /**
   * Pre flight checks regarding the provided options, making sure that the file can be opened (decrypted, decompressed), etc.
   */
  async bootstrap(diagnostics: IDiagnosticReporter) {
    this.#diagnostics = diagnostics;
    const { path: filePath } = this.options.file;

    try {
      // Read the metadata to ensure the file can be parsed
      await this.#loadMetadata();
      // TODO: we might also need to read the schema.jsonl files & implements a custom stream-check
    } catch {
      if (this.options?.encryption?.enabled) {
        throw new ProviderInitializationError(
          `Key is incorrect or the file '${filePath}' is not a valid Strapi data file.`
        );
      }
      throw new ProviderInitializationError(`File '${filePath}' is not a valid Strapi data file.`);
    }

    if (!this.#metadata) {
      throw new ProviderInitializationError('Could not load metadata from Strapi data file.');
    }
  }

  async #loadMetadata() {
    const backupStream = this.#getBackupStream();
    this.#metadata = await this.#parseJSONFile<IMetadata>(backupStream, METADATA_FILE_PATH);
  }

  async #loadAssetMetadata(path: string) {
    const backupStream = this.#getBackupStream();
    return this.#parseJSONFile<IFile>(backupStream, path);
  }

  async getMetadata() {

View on GitHub (pinned to 4a4101264d)

Solutions

1. Confirm the path points to a Strapi .data file produced by a compatible data-transfer version.
2. Re-create the export from the source instance.
3. Verify the file is not truncated/corrupted (compare size/checksum with source).
4. If the file is actually encrypted, set encryption.enabled = true and supply the key.

Example fix

// before
createLocalFileSourceProvider({ file: { path: './some-random-file' } });

// after
createLocalFileSourceProvider({ file: { path: './exports/backup-2024-01-01.data' } });

import { statSync } from 'fs';
const s = statSync(options.file.path);
if (!s.isFile() || s.size < 1024) throw new Error('File does not look like a Strapi data export');

function isInvalidFileError(e: unknown): boolean {
  return e instanceof Error && /is not a valid Strapi data file/.test(e.message);
}

try {
  await sourceProvider.bootstrap(diag);
} catch (e) {
  if (/not a valid Strapi data file/.test(e.message)) return { invalidFile: true };
  throw e;
}

When it happens

Trigger: File source bootstrap reads metadata and the underlying stream/JSON parse fails with encryption.enabled = false. Most often the path points to a non-.data file, a corrupted file, or a file from an incompatible Strapi version.

Common situations: Pointing file.path at the wrong file (a zip, a log, a partial download), an interrupted export that produced a truncated archive, an old v3/v4 export the current code cannot parse, or a file written by a different tool.

Related errors

• Could not load schemas from Strapi data file.
• Key is incorrect or the file '${filePath}' is not a valid St
• Could not load metadata from Strapi data file.
• Failed to read metadata for ${file}
• Invalid provider supplied. ${reason}

AI-assisted analysis of strapi/strapi@4a4101264d (2026-08-12). Data as JSON: /api/errors/eb9186b2b82210d3. Report an issue: GitHub.