What causes "Unable to find section blueprint with ID "%s"." in octobercms/october?

Run php artisan tailor:sync and php artisan cache:clear to ensure the blueprint registry matches the database

octobercms/october · error · SystemException

Unable to find section blueprint with ID "%s".

Error message

Unable to find section blueprint with ID "%s".

What it means

Thrown by getBlueprintDefinition() on entry records (HasEntryBlueprint trait) when the record has a blueprint_uuid but the BlueprintIndexer cannot find a matching section blueprint. The UUID is present in the database yet unknown to the current blueprint registry, so the lookup returns null and a SystemException with the UUID is raised.

Source

Thrown at modules/tailor/models/entryrecord/HasEntryBlueprint.php:55

    }

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

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

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

        return $this->blueprintCache = $blueprint;
    }

    /**
     * isEntryStructure
     */
    public function isEntryStructure(): bool
    {
        return $this->getBlueprintDefinition() instanceof StructureBlueprint;
    }

    /**
     * isEntryStream
     */
    public function isEntryStream(): bool
    {

View on GitHub (pinned to b608633a7e)

Solutions

Run php artisan tailor:sync and php artisan cache:clear to ensure the blueprint registry matches the database
If the section was deleted and recreated, update orphaned rows: set their blueprint_uuid to the new blueprint's UUID (find it via BlueprintIndexer::instance()->findSectionByHandle($handle)->uuid)
Restore the missing blueprint (re-import the tailoring file that defined it) so the UUID resolves again
If the data is disposable, delete the orphaned entry rows

Example fix

// Repair orphaned entries after a blueprint was recreated
$handle = 'blog_post';
$blueprint = \Tailor\Classes\BlueprintIndexer::instance()->findSectionByHandle($handle);
$oldUuid = '00000000-0000-0000-0000-000000000000';

\Tailor\Models\EntryRecord::where('blueprint_uuid', $oldUuid)
    ->update(['blueprint_uuid' => $blueprint->uuid]);

Defensive patterns

Strategy: validation

Validate before calling

// Confirm the UUID resolves before touching blueprint APIs
$blueprint = \Tailor\Classes\BlueprintIndexer::instance()->findSection($model->blueprint_uuid);
if (!$blueprint) {
    // reattach or skip this record
}

Type guard

function blueprintUuidResolves(?string $uuid): bool
{
    return $uuid !== null
        && \Tailor\Classes\BlueprintIndexer::instance()->findSection($uuid) !== null;
}

Prevention

Always deploy blueprint content together with database content (same release)
Avoid delete-and-recreate flows for blueprints with live data; edit in place to preserve the UUID
Add a maintenance command that reports entries whose blueprint_uuid no longer resolves

When it happens

Trigger: Entry rows whose blueprint_uuid references a blueprint that has been deleted or whose UUID changed (blueprints are content-synced, and recreating one can mint a new UUID); querying records after the section blueprint was removed; environments where the tailoring/blueprint data was never synced.

Common situations: Deleting and re-creating a section blueprint in Tailor while old entry rows keep the old UUID; pulling a database dump without pulling the matching blueprint content; partial tailor:sync runs; moving content between environments with mismatched blueprint identifiers.

Related errors

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