octobercms/october · error · BlueprintException

Invalid source reference '{$source}'. No blueprint found wit

Error message

Invalid source reference '{$source}'. No blueprint found with this handle or UUID.

What it means

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.

Source

Thrown at modules/tailor/classes/BlueprintVerifier.php:257

            }
        }
    }

    /**
     * validateSourceReferences validates source references in raw field config recursively
     */
    protected function validateSourceReferences(Blueprint $blueprint, array $fields)
    {
        foreach ($fields as $fieldName => $fieldConfig) {
            if (!is_array($fieldConfig)) {
                continue;
            }

            // Check source at this level
            $source = $fieldConfig['source'] ?? null;
            if ($source && !$this->sourceExists($source)) {
                $lineNo = $this->findLineFromKeyValPair($blueprint->content, 'source', $source);
                throw new BlueprintException(
                    $blueprint,
                    "Invalid source reference '{$source}'. No blueprint found with this handle or UUID.",
                    $lineNo
                );
            }

            // Recursively check nested fields in various structures
            $nestedFields = $fieldConfig['form']['fields']
                ?? $fieldConfig['fields']
                ?? null;

            if (is_array($nestedFields)) {
                $this->validateSourceReferences($blueprint, $nestedFields);
            }
        }
    }

    /**

View on GitHub (pinned to b608633a7e)

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.

Example fix

# before
fields:
  posts:
    type: entries
    source: blog/post   # typo: no blueprint with this handle

# after
fields:
  posts:
    type: entries
    source: blog/posts

Defensive patterns

Strategy: validation

Validate before calling

// Verify every source reference before running Tailor
$handles = [];
foreach (glob(themes_path().'/<theme>/blueprints/**/*.yaml') as $f) {
    $c = \Symfony\Component\Yaml\Yaml::parseFile($f);
    $handles[] = $c['handle'] ?? str_replace(themes_path('/', ''), '', $f);
}
// then check each field's source against known handles/UUIDs

Type guard

function sourceExists(string $source): bool
{
    return (bool) \Tailor\Classes\BlueprintIndexer::instance()->hasSection($source);
}

Try / catch

try {
    // tailor:refresh / blueprint save
} catch (\Tailor\Classes\BlueprintException $e) {
    // message names the source value; create the target blueprint or fix the handle
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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