octobercms/october · error · SystemException

Missing a blueprint definition in import/export model.

Error message

Missing a blueprint definition in import/export model.

What it means

Thrown by the BlueprintModel trait's getBlueprintDefinition() (used by Tailor import/export models) when the model has no blueprint_uuid set. Import and export models must be bound to a blueprint before use; when the UUID attribute is empty a SystemException is raised with this message.

Source

Thrown at modules/tailor/traits/BlueprintModel.php:50

     * setBlueprintUuid
     */
    public function setBlueprintUuid($value)
    {
        $this->blueprint_uuid = $value;
    }

    /**
     * getBlueprintDefinition
     */
    public function getBlueprintDefinition(): Blueprint
    {
        if ($this->blueprintCache !== null) {
            return $this->blueprintCache;
        }

        $uuid = $this->blueprint_uuid;
        if (!$uuid) {
            throw new SystemException('Missing a blueprint definition in import/export model.');
        }

        $blueprint = BlueprintIndexer::instance()->find($uuid);
        if (!$blueprint) {
            throw new SystemException(sprintf('Unable to find import/export blueprint with ID "%s".', $uuid));
        }

        return $this->blueprintCache = $blueprint;
    }

    /**
     * getContentFieldsetDefinition
     */
    public function getContentFieldsetDefinition(): Fieldset
    {
        $fieldset = BlueprintIndexer::instance()->findContentFieldset($this->blueprint_uuid);

        if (!$fieldset) {

View on GitHub (pinned to b608633a7e)

Solutions

1. Ensure the import/export model is initialized through Tailor's import/export flow so the blueprint UUID is assigned
2. If writing a custom model with this trait, resolve and set blueprint_uuid (setBlueprintUuid) before calling blueprint-dependent methods
3. Check that the importer/exporter configuration references an existing section/global blueprint

Example fix

// before
$model = new MyImportModel;
$blueprint = $model->getBlueprintDefinition();  // throws

// after
$model = new MyImportModel;
$model->setBlueprintUuid($blueprintUuid);
$blueprint = $model->getBlueprintDefinition();

// Bind the blueprint before use
if (empty($importModel->blueprint_uuid)) {
    $importModel->setBlueprintUuid($resolvedBlueprintUuid);
}

When it happens

Trigger: Using an import/export model class that uses BlueprintModel without defining which blueprint it belongs to — i.e. blueprint_uuid is null because the model was instantiated outside its intended initialization path or the configuration was not applied.

Common situations: Custom classes adopting the BlueprintModel trait without implementing the required initialization; importers constructed before the blueprint was resolved; bugs in custom import/export workflows that skip the blueprint binding step.

Related errors

• Missing section definition. Call EntryRecord::inSection() to
• Missing global definition. Call GlobalRecord::inGlobal() to
• Unable to find import/export blueprint with ID "%s".
• Unable to find content fieldset definition with UUID of '{$t
• Unable to find section blueprint with ID "%s".

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/c4fa7ffcebbd79b0. Report an issue: GitHub.