octobercms/october · error · SystemException

Plugin configuration file plugin.yaml is not found for the p

Error message

Plugin configuration file plugin.yaml is not found for the plugin class %s. Create the file or override pluginDetails() method in the plugin class.

What it means

PluginBase::getConfigurationFromYaml() looks for plugin.yaml next to the plugin's Plugin.php. When the file does not exist and the caller passed a non-null $exceptionMessage (the default pluginDetails() implementation does this), a SystemException is thrown instead of silently returning an empty config. It means the plugin is expected to declare its metadata (name, description, author, icon) in plugin.yaml but that file is absent. The exception message itself tells you the two ways out: create the file, or override pluginDetails() in the plugin class.

Source

Thrown at modules/system/classes/PluginBase.php:325

            return $this->loadedYamlConfiguration;
        }

        $reflection = new ReflectionClass(get_class($this));
        $yamlFilePath = dirname($reflection->getFileName()).'/plugin.yaml';

        if (file_exists($yamlFilePath)) {
            $this->loadedYamlConfiguration = Yaml::parse(file_get_contents($yamlFilePath));

            if (!is_array($this->loadedYamlConfiguration)) {
                throw new SystemException(sprintf(
                    'Invalid format of the plugin configuration file: %s. The file should define an array.',
                    $yamlFilePath
                ));
            }
        }
        else {
            if ($exceptionMessage !== null) {
                throw new SystemException($exceptionMessage);
            }

            $this->loadedYamlConfiguration = [];
        }

        return $this->loadedYamlConfiguration;
    }
}

View on GitHub (pinned to b608633a7e)

Solutions

1. Create plugin.yaml in the plugin root (same directory as Plugin.php) with a top-level array containing plugin, name, description, author, icon keys
2. Or override pluginDetails(): array in your Plugin class and return the details array directly, bypassing the yaml lookup
3. Check the exact filename casing and extension: it must be lowercase 'plugin.yaml', not plugin.yml or Plugin.yaml
4. Verify the file actually deployed to the server (rsync/git archive exclusions) and clear cached plugin metadata if present

Example fix

// before — plugin has no plugin.yaml and relies on the default pluginDetails()
class Plugin extends \System\Classes\PluginBase
{
}
// after — override pluginDetails() so the yaml file is not required
class Plugin extends \System\Classes\PluginBase
{
    public function pluginDetails(): array
    {
        return [
            'name' => 'My Plugin',
            'description' => 'Adds features.',
            'author' => 'Me',
            'icon' => 'icon-leaf',
        ];
    }
}

// Before relying on plugin.yaml, confirm it ships with the plugin
$pluginFile = (new ReflectionClass(\My\Plugin\Plugin::class))->getFileName();
$hasYaml = file_exists(dirname($pluginFile) . '/plugin.yaml');
if (!$hasYaml && !method_exists(\My\Plugin\Plugin::class, 'pluginDetails')) {
    // details lookup will throw — create the yaml or add pluginDetails() before enabling
}

try {
    $details = \System\Classes\PluginManager::instance()->findByIdentifier('Author.Plugin')->pluginDetails();
} catch (\System\Classes\SystemException $ex) {
    // plugin.yaml missing and no pluginDetails() override — degrade to defaults
    $details = ['name' => 'Author.Plugin', 'description' => ''];
}

When it happens

Trigger: Instantiating a plugin whose default pluginDetails() method is asked for details (e.g. PluginManager listing/registration or the backend plugin list) while plugins/<author>/<plugin>/plugin.yaml is missing. Only hit when $exceptionMessage was passed, i.e. the strict path; other callers would just get [].

Common situations: plugin.yaml forgotten in a git commit or excluded by .gitignore/deploy pipeline; file renamed (Plugin.yaml, plugin.yml) so file_exists() fails; plugin skeleton generated without the yaml; plugin migrated from another install where details came from an override that was dropped.

Related errors

• backend::lang.field.invalid_type
• The plugin configuration file plugin.yaml should contain the
• Invalid format of the plugin configuration file: %s. The fil
• Too much recursion! Check for circular dependencies in your
• Package [$name] not found

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