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

Confirm the exact handle in the blueprint YAML (the handle: property of the section) and use it verbatim in inSection()

octobercms/october · error · SystemException

Section handle [{$handle}] not found

Error message

Section handle [{$handle}] not found

What it means

Thrown by EntryRecord::inSection($handle) when the BlueprintIndexer cannot resolve the given section handle to a blueprint. The indexer maintains a registry of blueprints defined in tailoring files/blueprints; if no section blueprint matches the handle, a SystemException is raised before any query is built.

Source

Thrown at modules/tailor/models/EntryRecord.php:218

        $this->setPublishingDates($this->published_at ?: $this->freshTimestamp());
    }

    /**
     * setPublishingDates
     */
    protected function setPublishingDates($useDate)
    {
        $this->published_at_date = $useDate;
    }

    /**
     * inSection
     */
    public static function inSection($handle)
    {
        $blueprint = BlueprintIndexer::instance()->findSectionByHandle($handle);
        if (!$blueprint) {
            throw new SystemException("Section handle [{$handle}] not found");
        }

        $model = $blueprint->newModelInstance();

        return $model::inSectionUuid($blueprint->uuid);
    }

    /**
     * inSectionUuid
     */
    public static function inSectionUuid($uuid)
    {
        $instance = new static;

        $instance->extendWithBlueprint($uuid);

        return $instance;
    }

View on GitHub (pinned to b608633a7e)

Solutions

Confirm the exact handle in the blueprint YAML (the handle: property of the section) and use it verbatim in inSection()
Run php artisan tailor:sync (and php artisan cache:clear) so the blueprint indexer picks up newly added or changed blueprints
If the blueprint was renamed, update every call site (pages, components, partials) to the new handle
Check for case mismatches: handles like Blog vs blog are not interchangeable

Example fix

// before
$records = \Tailor\Models\EntryRecord::inSection('BlogPost')->get();  // handle is blog_post

// after
$records = \Tailor\Models\EntryRecord::inSection('blog_post')->get();

Defensive patterns

Strategy: validation

Validate before calling

// Resolve the handle safely before querying
$blueprint = \Tailor\Classes\BlueprintIndexer::instance()->findSectionByHandle($handle);
if (!$blueprint) {
    // fallback: log, return empty collection, or use a default section
    return collect();
}
$records = \Tailor\Models\EntryRecord::inSectionUuid($blueprint->uuid)->get();

Type guard

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

Prevention

Run php artisan tailor:sync as part of every deployment pipeline
Centralize section handles as constants or a config map instead of scattering string literals through templates
After renaming a blueprint handle, grep the whole codebase for the old handle before deploying

When it happens

Trigger: Calling EntryRecord::inSection('handle') with a handle that does not match any section blueprint: typo, wrong case (handles are case-sensitive), referencing a blueprint that has not been created yet, or calling before Tailor has indexed the blueprints.

Common situations: Hardcoding a handle in theme code or a component that drifts out of sync with renamed blueprints; blueprints not synced after pulling code (tailor migrations are DB-stored); environment differences where the blueprint file exists in one environment but not another; handle renamed in YAML but old handle still used in page code.

Related errors

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