{"record":{"id":"90bef7233d112a5b","repo":"BookStackApp/BookStack","slug":"errors-import-validation-failed","errorCode":null,"errorMessage":"errors.import_validation_failed","messagePattern":"errors\\.import_validation_failed","errorType":"validation","errorClass":"ZipImportException","httpStatus":null,"severity":"error","filePath":"app/Exports/ZipExports/ZipImportRunner.php","lineNumber":58,"sourceCode":"        protected ZipImportReferences $references,\n    ) {\n    }\n\n    /**\n     * Run the import.\n     * Performs re-validation on zip, validation on parent provided, and permissions for importing\n     * the planned content, before running the import process.\n     * Returns the top-level entity item which was imported.\n     * @throws ZipImportException\n     */\n    public function run(Import $import, Book|Chapter|null $parent = null): Entity\n    {\n        $zipPath = $this->getZipPath($import);\n        $reader = new ZipExportReader($zipPath);\n\n        $errors = (new ZipExportValidator($reader))->validate();\n        if ($errors) {\n            throw new ZipImportException([\n                trans('errors.import_validation_failed'),\n                ...$errors,\n            ]);\n        }\n\n        try {\n            $exportModel = $reader->decodeDataToExportModel();\n        } catch (ZipExportException $e) {\n            throw new ZipImportException([$e->getMessage()]);\n        }\n\n        // Validate parent type\n        if ($exportModel instanceof ZipExportBook && ($parent !== null)) {\n            throw new ZipImportException([\"Must not have a parent set for a Book import.\"]);\n        } else if ($exportModel instanceof ZipExportChapter && !($parent instanceof Book)) {\n            throw new ZipImportException([\"Parent book required for chapter import.\"]);\n        } else if ($exportModel instanceof ZipExportPage && !($parent instanceof Book || $parent instanceof Chapter)) {\n            throw new ZipImportException([\"Parent book or chapter required for page import.\"]);","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/BookStackApp/BookStack/blob/18f8469a1c72f8cc8497e9372635e6dea5028071/app/Exports/ZipExports/ZipImportRunner.php#L40-L76","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the additional messages in the exception array after the first — they name the exact validation failures.","Fix those fields in data.json or regenerate the export from a compatible BookStack version.","Verify the export and import instances run compatible BookStack major versions.","Validate manually by running the export through ZipExportValidator in a test/tinker script."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"$reader = new \\BookStack\\Exports\\ZipExports\\ZipExportReader($zipPath);\n$errors = (new \\BookStack\\Exports\\ZipExports\\ZipExportValidator($reader))->validate();\nif ($errors) {\n    foreach ($errors as $err) { echo $err, PHP_EOL; } // fix these first\n    exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n    (new ZipImportRunner(...))->run($import, $parent);\n} catch (\\BookStack\\Exceptions\\ZipImportException $e) {\n    foreach ($e->getMessage() as $msg) { /* first msg is generic; rest are specifics */ }\n}","preventionTips":["Run ZipExportValidator manually before committing to an import.","Keep export and import BookStack versions aligned.","Never hand-edit export payloads without re-validating.","Ensure referenced images/attachments exist in the archive."],"tags":["zip-import","bookstack","validation"],"backgroundTag":"import-validation-failed","analyzedSha":"18f8469a1c72f8cc8497e9372635e6dea5028071","analyzedAt":"2026-09-02T19:49:33.068Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}