octobercms/october · error · SystemException

The plugin configuration file plugin.yaml should contain the

Error message

The plugin configuration file plugin.yaml should contain the "plugin" section: %s.

What it means

PluginBase::pluginDetails() supplies the name/description/author shown in the backend by reading the plugin.yaml sitting next to the plugin class (getConfigurationFromYaml). If the file exists and parses but contains no top-level 'plugin' key, SystemException is thrown naming the plugin class. Most plugins instead override pluginDetails() and return the array directly, so this path hits code relying on the YAML-driven flow.

Source

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

     * @return array
     * @throws SystemException
     */
    public function pluginDetails()
    {
        $thisClass = get_class($this);

        $configuration = $this->getConfigurationFromYaml(sprintf(
            'Plugin configuration file plugin.yaml is not '.
            'found for the plugin class %s. Create the file or override pluginDetails() '.
            'method in the plugin class.',
            $thisClass
        ));

        if (array_key_exists('plugin', $configuration)) {
            return $configuration['plugin'];
        }

        throw new SystemException(sprintf(
            'The plugin configuration file plugin.yaml should contain the "plugin" section: %s.',
            $thisClass
        ));
    }

    /**
     * register method, called when the plugin is first registered.
     */
    public function register()
    {
    }

    /**
     * @inheritDoc
     */
    public function registerMarkupTags()
    {
        return [];

View on GitHub (pinned to b608633a7e)

Solutions

1. Add the missing top-level section to plugin.yaml with at least name, description and author (icon optional).
2. Alternatively override pluginDetails() in the plugin class to return the array directly and stop relying on the YAML.
3. Validate indentation — 'plugin:' nested one level too deep parses as a child of another key.

Example fix

# before — plugin.yaml
navigation:
  main: ...

# after — plugin.yaml
plugin:
  name: Blog
  description: 'Blog management'
  author: Acme
  icon: icon-pencil
navigation:
  main: ...

// In tests or a boot check, verify the yaml carries the section
use Symfony\Component\Yaml\Yaml;

function pluginYamlHasPluginSection(string $pluginClass): bool
{
    $ref = new ReflectionClass($pluginClass);
    $file = dirname($ref->getFileName()) . '/plugin.yaml';
    if (!file_exists($file)) return false;
    $config = Yaml::parse(file_get_contents($file));
    return is_array($config) && array_key_exists('plugin', $config);
}

When it happens

Trigger: Creating plugin.yaml with other sections (navigation, permissions) but omitting the plugin: block; overriding pluginDetails() to call parent::pluginDetails() while the YAML lacks the section; scaffolding a plugin where the yaml template was trimmed.

Common situations: Plugin scaffolding by hand or by generator that writes a partial plugin.yaml; upgrading plugins where the yaml was reorganized and the plugin key was dropped; the backend system settings page or plugin list requesting details from every registered plugin.

Related errors

• Invalid format of the plugin configuration file: %s. The fil
• Key property (${keyProperty}) value should be a string. Prop
• cms::lang.component.not_found
• Unknown dimension type:
• Plugin configuration file plugin.yaml is not found for the p

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