BookStackApp/BookStack · error · ZipImportException

errors.import_validation_failed

Error message

errors.import_validation_failed

What it means

ZipImportRunner::run() validates the ZIP export with ZipExportValidator before importing. If validate() returns any errors, it throws ZipImportException whose message array starts with the localized 'errors.import_validation_failed' followed by the specific validation error messages. This is a gate ensuring the export's declared entities and structure can actually be imported.

Source

Thrown at app/Exports/ZipExports/ZipImportRunner.php:58

        protected ZipImportReferences $references,
    ) {
    }

    /**
     * Run the import.
     * Performs re-validation on zip, validation on parent provided, and permissions for importing
     * the planned content, before running the import process.
     * Returns the top-level entity item which was imported.
     * @throws ZipImportException
     */
    public function run(Import $import, Book|Chapter|null $parent = null): Entity
    {
        $zipPath = $this->getZipPath($import);
        $reader = new ZipExportReader($zipPath);

        $errors = (new ZipExportValidator($reader))->validate();
        if ($errors) {
            throw new ZipImportException([
                trans('errors.import_validation_failed'),
                ...$errors,
            ]);
        }

        try {
            $exportModel = $reader->decodeDataToExportModel();
        } catch (ZipExportException $e) {
            throw new ZipImportException([$e->getMessage()]);
        }

        // Validate parent type
        if ($exportModel instanceof ZipExportBook && ($parent !== null)) {
            throw new ZipImportException(["Must not have a parent set for a Book import."]);
        } else if ($exportModel instanceof ZipExportChapter && !($parent instanceof Book)) {
            throw new ZipImportException(["Parent book required for chapter import."]);
        } else if ($exportModel instanceof ZipExportPage && !($parent instanceof Book || $parent instanceof Chapter)) {
            throw new ZipImportException(["Parent book or chapter required for page import."]);

View on GitHub (pinned to 18f8469a1c)

Solutions

1. Read the additional messages in the exception array after the first — they name the exact validation failures.
2. Fix those fields in data.json or regenerate the export from a compatible BookStack version.
3. Verify the export and import instances run compatible BookStack major versions.
4. Validate manually by running the export through ZipExportValidator in a test/tinker script.

$reader = new \BookStack\Exports\ZipExports\ZipExportReader($zipPath);
$errors = (new \BookStack\Exports\ZipExports\ZipExportValidator($reader))->validate();
if ($errors) {
    foreach ($errors as $err) { echo $err, PHP_EOL; } // fix these first
    exit(1);
}

try {
    (new ZipImportRunner(...))->run($import, $parent);
} catch (\BookStack\Exceptions\ZipImportException $e) {
    foreach ($e->getMessage() as $msg) { /* first msg is generic; rest are specifics */ }
}

When it happens

Trigger: Any ZipExportValidator failure: missing/invalid meta data, unsupported export format version, references to nonexistent relations, or per-entity validation errors inside book/chapter/page payloads.

Common situations: Imports across mismatched BookStack versions (validator requires newer meta fields); hand-edited exports missing required fields; exports referencing images/attachments not present in the archive.

Related errors

• Book to move chapter into not found
• Book or chapter to move page into not found
• Selected parent is not a book or chapter
• errors.import_zip_cant_decode_data
• errors.import_zip_data_too_large

AI-assisted analysis of BookStackApp/BookStack@18f8469a1c (2026-09-02). Data as JSON: /api/errors/90bef7233d112a5b. Report an issue: GitHub.