What causes "Blueprint not found" in octobercms/october?

Reload the blueprint list in the editor so stale paths disappear, then re-open the file under its current name/path.

octobercms/october · error · ApplicationException

Blueprint not found

Error message

Blueprint not found

What it means

loadTemplate() resolves the document type to the Blueprint or ThemeBlueprint class and calls load($path); a null return means no blueprint file matches that path. The handler converts this into an ApplicationException carrying the tailor::lang.blueprint.not_found message, which is surfaced to the editor user.

Source

Thrown at modules/tailor/classes/editorextension/HasExtensionCrud.php:215

    protected function command_onBlueprintUpload()
    {
        $this->assertBlueprintPermissions();

        $this->editorUploadFiles($this->getBlueprintsPath(), ['yaml']);
    }

    /**
     * loadTemplate returns an existing template of a given type
     * @param string $documentType
     * @param string $path
     * @return mixed
     */
    private function loadTemplate($documentType, $path)
    {
        $class = $this->resolveTypeClassName($documentType);

        if (!($template = call_user_func([$class, 'load'], $path))) {
            throw new ApplicationException(trans('tailor::lang.blueprint.not_found'));
        }

        return $template;
    }

    /**
     * resolveTypeClassName resolves a template type to its class name
     * @param string $documentType
     * @return string
     */
    private function resolveTypeClassName($documentType)
    {
        $types = [
            EditorExtension::DOCUMENT_TYPE_BLUEPRINT => Blueprint::class,
            EditorExtension::DOCUMENT_TYPE_THEME_BLUEPRINT => ThemeBlueprint::class
        ];

        if (!array_key_exists($documentType, $types)) {

View on GitHub (pinned to b608633a7e)

Solutions

Reload the blueprint list in the editor so stale paths disappear, then re-open the file under its current name/path.
If the file was deleted unintentionally, restore it from VCS or backup and retry.
For programmatic calls, verify the file exists (or handle a null return from load()) before issuing open/save commands.

Example fix

// before
$template = $this->loadTemplate($documentType, $path);

// after
if (!file_exists(base_path($path))) {
    throw new ApplicationException('Blueprint file no longer exists: ' . $path);
}
$template = $this->loadTemplate($documentType, $path);

Defensive patterns

Strategy: try-catch

Validate before calling

if (!call_user_func([$class, 'load'], $path)) {
    // path stale — refresh the document list instead of proceeding
}

Try / catch

try {
    $template = $this->loadTemplate($documentType, $path);
} catch (\October\Rain\Exception\ApplicationException $e) {
    // blueprint file gone: sync the file list, surface 'not found' to the user, offer to reload
}

Prevention

Handle file deletions/renames in the editor by reloading the blueprint tree.
In custom integrations, check the blueprint file exists before issuing open/save commands.
Use VCS so accidentally deleted blueprint files can be restored.

When it happens

Trigger: Opening or saving a blueprint in the editor whose path no longer exists — the file was deleted or renamed on disk, the path went stale after moving blueprints between themes, or the editor client cached an outdated document path.

Common situations: Another editor or a git branch switch deleted/renamed the file while the document was open; renaming a blueprint directory; programmatic CRUD calls with hardcoded paths after a refactor.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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