{"record":{"id":"52064cb49c6f57b3","repo":"octobercms/october","slug":"invalid-source-reference-source-no-blueprint","errorCode":null,"errorMessage":"Invalid source reference '{$source}'. No blueprint found with this handle or UUID.","messagePattern":"Invalid source reference '(.+?)'\\. No blueprint found with this handle or UUID\\.","errorType":"exception","errorClass":"BlueprintException","httpStatus":null,"severity":"error","filePath":"modules/tailor/classes/BlueprintVerifier.php","lineNumber":257,"sourceCode":"            }\n        }\n    }\n\n    /**\n     * validateSourceReferences validates source references in raw field config recursively\n     */\n    protected function validateSourceReferences(Blueprint $blueprint, array $fields)\n    {\n        foreach ($fields as $fieldName => $fieldConfig) {\n            if (!is_array($fieldConfig)) {\n                continue;\n            }\n\n            // Check source at this level\n            $source = $fieldConfig['source'] ?? null;\n            if ($source && !$this->sourceExists($source)) {\n                $lineNo = $this->findLineFromKeyValPair($blueprint->content, 'source', $source);\n                throw new BlueprintException(\n                    $blueprint,\n                    \"Invalid source reference '{$source}'. No blueprint found with this handle or UUID.\",\n                    $lineNo\n                );\n            }\n\n            // Recursively check nested fields in various structures\n            $nestedFields = $fieldConfig['form']['fields']\n                ?? $fieldConfig['fields']\n                ?? null;\n\n            if (is_array($nestedFields)) {\n                $this->validateSourceReferences($blueprint, $nestedFields);\n            }\n        }\n    }\n\n    /**","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/tailor/classes/BlueprintVerifier.php#L239-L275","documentation":"During blueprint validation, every `source:` key found in raw field config (checked recursively, including nested `fields` and `form.fields` blocks) must resolve to an existing blueprint by handle or UUID via sourceExists(). If no known blueprint matches, validation aborts with the line number of the offending `source:` key.","triggerScenarios":"An entries/recordfinder field uses `source: blog/posts` but no blueprint with that handle or UUID exists — typo, target blueprint file deleted or renamed, or the target lives in an inactive theme so it is never indexed by the verifier.","commonSituations":"Creating a referencing field before creating the target blueprint; renaming a blueprint without updating references; copying blueprints between themes or projects where the target doesn't exist; references to a UUID that changed when a file was recreated.","solutions":["Set `source:` to the exact handle (blueprint directory path) or UUID of an existing blueprint.","Create the missing target blueprint first, then re-run `php artisan tailor:refresh`.","If the target blueprint exists in another theme, activate that theme or copy the blueprint into the active theme."],"exampleFix":"# before\nfields:\n  posts:\n    type: entries\n    source: blog/post   # typo: no blueprint with this handle\n\n# after\nfields:\n  posts:\n    type: entries\n    source: blog/posts","handlingStrategy":"validation","validationCode":"// Verify every source reference before running Tailor\n$handles = [];\nforeach (glob(themes_path().'/<theme>/blueprints/**/*.yaml') as $f) {\n    $c = \\Symfony\\Component\\Yaml\\Yaml::parseFile($f);\n    $handles[] = $c['handle'] ?? str_replace(themes_path('/', ''), '', $f);\n}\n// then check each field's source against known handles/UUIDs","typeGuard":"function sourceExists(string $source): bool\n{\n    return (bool) \\Tailor\\Classes\\BlueprintIndexer::instance()->hasSection($source);\n}","tryCatchPattern":"try {\n    // tailor:refresh / blueprint save\n} catch (\\Tailor\\Classes\\BlueprintException $e) {\n    // message names the source value; create the target blueprint or fix the handle\n}","preventionTips":["Create target blueprints before fields that reference them.","Prefer stable handles over UUIDs in source references so renames are explicit.","After renaming or deleting a blueprint, grep all blueprints for its old handle and update references."],"tags":["tailor","source-reference","blueprint","validation"],"backgroundTag":"unresolved-reference","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}