octobercms/october · error · SystemException

Missing global definition. Call GlobalRecord::inGlobal() to

Error message

Missing global definition. Call GlobalRecord::inGlobal() to set one.

What it means

Thrown by getBlueprintDefinition() on global records (HasGlobalBlueprint trait) when the model instance has no blueprint_uuid attribute. Global records must be attached to a global blueprint via GlobalRecord::inGlobal()/inGlobalUuid() before blueprint-dependent APIs are used; a SystemException is raised when the UUID is missing.

Source

Thrown at modules/tailor/models/globalrecord/HasGlobalBlueprint.php:76

     * globalBeforeSaveDone
     */
    public function globalBeforeSaveDone()
    {
        $this->storeBlueprintContent();
    }

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

        $uuid = $this->blueprint_uuid;
        if (!$uuid) {
            throw new SystemException('Missing global definition. Call GlobalRecord::inGlobal() to set one.');
        }

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

        return $this->blueprintCache = $blueprint;
    }

    /**
     * fetchBlueprintContent
     */
    public function fetchBlueprintContent()
    {
        $content = $this->content;
        $contentColumns = $this->getFieldsetColumnNames();

View on GitHub (pinned to b608633a7e)

Solutions

Use GlobalRecord::inGlobal('handle') / findForGlobal('handle') to obtain properly attached models
When creating programmatically, resolve the blueprint first and set the UUID on the instance before save
Repair rows with null blueprint_uuid by assigning the intended global blueprint's UUID

Example fix

// before
$global = new \Tailor\Models\GlobalRecord;
$global->save();  // blueprint access later throws

// after
$blueprint = \Tailor\Classes\BlueprintIndexer::instance()->findGlobalByHandle('site_settings');
$global = \Tailor\Models\GlobalRecord::findForGlobalUuid($blueprint->uuid);

Defensive patterns

Strategy: validation

Validate before calling

if (empty($global->blueprint_uuid)) {
    $blueprint = \Tailor\Classes\BlueprintIndexer::instance()->findGlobalByHandle('site_settings');
    $global->blueprint_uuid = $blueprint->uuid;
}

Type guard

function isGlobalAttached(\Tailor\Models\GlobalRecord $record): bool
{
    return !empty($record->blueprint_uuid);
}

Prevention

Obtain global records only via GlobalRecord::inGlobal()/findForGlobal() so the UUID is always set
Write seeders through the section/global APIs rather than raw inserts
Copy blueprint_uuid when duplicating global records across sites

When it happens

Trigger: Instantiating GlobalRecord directly (new GlobalRecord) and calling methods that need the blueprint (content fields, fieldset definitions); creating global rows without the blueprint UUID; accessing blueprint APIs on rows whose blueprint_uuid is null.

Common situations: Seeding or import scripts creating global records outside the Tailor APIs; custom code copying global records between sites without preserving blueprint_uuid.

Related errors

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