What causes "Global handle [{$handle}] not found" in octobercms/october?

Use the exact handle: value from the global blueprint YAML

octobercms/october · error · ApplicationException

Global handle [{$handle}] not found

Error message

Global handle [{$handle}] not found

What it means

Thrown by GlobalRecord::findForGlobal($handle) when the BlueprintIndexer cannot find a global blueprint matching the handle. Globals are Tailor's singleton blueprints (header/footer scripts, site settings); this method resolves the handle to a UUID and throws an ApplicationException (user-facing) if no blueprint matches.

Source

Thrown at modules/tailor/models/GlobalRecord.php:84

        $this->getFieldsetDefinition()->defineAllFormFields($host);
    }

    /**
     * afterBoot
     */
    public function afterBoot()
    {
        static::addGlobalScope(new GlobalRecordScope);
    }

    /**
     * findForGlobal
     */
    public static function findForGlobal($handle): GlobalRecord
    {
        $blueprint = BlueprintIndexer::instance()->findGlobalByHandle($handle);
        if (!$blueprint) {
            throw new ApplicationException("Global handle [{$handle}] not found");
        }

        return static::findForGlobalUuid($blueprint->uuid);
    }

    /**
     * findForGlobalUuid
     */
    public static function findForGlobalUuid($uuid): GlobalRecord
    {
        // Find existing record
        $record = static::inGlobalUuid($uuid)->first();
        if ($record) {
            return $record;
        }

        // Create new record
        $global = new static;

View on GitHub (pinned to b608633a7e)

Solutions

Use the exact handle: value from the global blueprint YAML
Run php artisan tailor:sync and php artisan cache:clear to index the blueprint
Update theme/component references after renaming a global handle
Prefer the tailor globals CMS component (alias lookup) instead of hardcoded handles where possible

Example fix

// before
$global = \Tailor\Models\GlobalRecord::findForGlobal('SiteSettings');

// after
$global = \Tailor\Models\GlobalRecord::findForGlobal('site_settings');

Defensive patterns

Strategy: validation

Validate before calling

$blueprint = \Tailor\Classes\BlueprintIndexer::instance()->findGlobalByHandle($handle);
if (!$blueprint) {
    // graceful fallback for missing global
    return new \Tailor\Models\GlobalRecord;
}
$global = \Tailor\Models\GlobalRecord::findForGlobalUuid($blueprint->uuid);

Type guard

function globalHandleExists(string $handle): bool
{
    return \Tailor\Classes\BlueprintIndexer::instance()->findGlobalByHandle($handle) !== null;
}

Prevention

Prefer the tailor globals component over hardcoded findForGlobal calls in themes
Run tailor:sync on every deploy so global handles always resolve
Rename-proof templates by routing handles through a single helper or config map

When it happens

Trigger: Calling GlobalRecord::findForGlobal('handle') in theme code or a component with a handle that does not match any global blueprint: typo, case mismatch, blueprint not synced, or blueprint not present in the current environment.

Common situations: Hardcoding global handles in layout templates; renaming a global blueprint without updating the templates that fetch it; fresh deployments where blueprints/ directory contents are DB-synced separately; using the global's title instead of its handle.

Related errors

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