octobercms/october · error · SystemException

Invalid format of the plugin configuration file: %s. The fil

Error message

Invalid format of the plugin configuration file: %s. The file should define an array.

What it means

PluginBase::getConfigurationFromYaml() reads dirname(plugin class file)/plugin.yaml and parses it with Yaml::parse. If the parse result is not a PHP array — an empty file parses to null, a single scalar document parses to a string/number — SystemException is thrown naming the file path. Distinct from the missing-file case (which only throws when pluginDetails() supplies its own exception message) and from the missing-'plugin'-section case: here the file exists but its top-level structure is wrong.

Source

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

     * getConfigurationFromYaml reads configuration from YAML file.
     * @param string|null $exceptionMessage
     * @return array|bool
     * @throws SystemException
     */
    protected function getConfigurationFromYaml($exceptionMessage = null)
    {
        if ($this->loadedYamlConfiguration !== false) {
            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. Make plugin.yaml a proper top-level mapping (key: value lines) — the file must define an array.
2. If the file is intentionally empty, delete it and override pluginDetails() in the plugin class instead.
3. Lint the file: php -r "var_export(Symfony\Component\Yaml\Yaml::parse(file_get_contents('plugins/acme/blog/plugin.yaml')));" must print an array.

Example fix

# before — plugins/acme/blog/plugin.yaml (empty file, parses to null)

# after
plugin:
  name: Blog
  description: 'Blog management'
  author: Acme
  icon: icon-pencil

// Assert the yaml document parses to an array before the framework reads it
use Symfony\Component\Yaml\Yaml;

function pluginYamlParsesToArray(string $path): bool
{
    if (!file_exists($path)) return false;
    $parsed = Yaml::parse(file_get_contents($path));
    return is_array($parsed);
}

When it happens

Trigger: An empty plugin.yaml (created as a placeholder, returns null); plugin.yaml containing only a scalar or comment-free plain string; a YAML document that parses to a list (- item lines) rather than a mapping; copy/paste that left stray characters making the whole document one scalar.

Common situations: Placeholder yaml files committed empty so the 'file not found' error goes away; YAML indentation mistakes that turn the mapping into a single string; content pasted with tabs or template placeholders that flatten the document.

Related errors

• The plugin configuration file plugin.yaml should contain the
• 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/ac02a9fec69e2288. Report an issue: GitHub.