{"record":{"id":"f41b7a4da9bd8248","repo":"octobercms/october","slug":"global-handle-handle-not-found","errorCode":null,"errorMessage":"Global handle [{$handle}] not found","messagePattern":"Global handle \\[(.+?)\\] not found","errorType":"exception","errorClass":"ApplicationException","httpStatus":null,"severity":"error","filePath":"modules/tailor/models/GlobalRecord.php","lineNumber":84,"sourceCode":"        $this->getFieldsetDefinition()->defineAllFormFields($host);\n    }\n\n    /**\n     * afterBoot\n     */\n    public function afterBoot()\n    {\n        static::addGlobalScope(new GlobalRecordScope);\n    }\n\n    /**\n     * findForGlobal\n     */\n    public static function findForGlobal($handle): GlobalRecord\n    {\n        $blueprint = BlueprintIndexer::instance()->findGlobalByHandle($handle);\n        if (!$blueprint) {\n            throw new ApplicationException(\"Global handle [{$handle}] not found\");\n        }\n\n        return static::findForGlobalUuid($blueprint->uuid);\n    }\n\n    /**\n     * findForGlobalUuid\n     */\n    public static function findForGlobalUuid($uuid): GlobalRecord\n    {\n        // Find existing record\n        $record = static::inGlobalUuid($uuid)->first();\n        if ($record) {\n            return $record;\n        }\n\n        // Create new record\n        $global = new static;","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/tailor/models/GlobalRecord.php#L66-L102","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n$global = \\Tailor\\Models\\GlobalRecord::findForGlobal('SiteSettings');\n\n// after\n$global = \\Tailor\\Models\\GlobalRecord::findForGlobal('site_settings');","handlingStrategy":"validation","validationCode":"$blueprint = \\Tailor\\Classes\\BlueprintIndexer::instance()->findGlobalByHandle($handle);\nif (!$blueprint) {\n    // graceful fallback for missing global\n    return new \\Tailor\\Models\\GlobalRecord;\n}\n$global = \\Tailor\\Models\\GlobalRecord::findForGlobalUuid($blueprint->uuid);","typeGuard":"function globalHandleExists(string $handle): bool\n{\n    return \\Tailor\\Classes\\BlueprintIndexer::instance()->findGlobalByHandle($handle) !== null;\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["tailor","octobercms","blueprint","global","handle","indexer","singleton"],"backgroundTag":"handle-not-found","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}