{"record":{"id":"ac02a9fec69e2288","repo":"octobercms/october","slug":"invalid-format-of-the-plugin-configuration-file","errorCode":null,"errorMessage":"Invalid format of the plugin configuration file: %s. The file should define an array.","messagePattern":"Invalid format of the plugin configuration file: (.+?)\\. The file should define an array\\.","errorType":"exception","errorClass":"SystemException","httpStatus":null,"severity":"error","filePath":"modules/system/classes/PluginBase.php","lineNumber":317,"sourceCode":"     * getConfigurationFromYaml reads configuration from YAML file.\n     * @param string|null $exceptionMessage\n     * @return array|bool\n     * @throws SystemException\n     */\n    protected function getConfigurationFromYaml($exceptionMessage = null)\n    {\n        if ($this->loadedYamlConfiguration !== false) {\n            return $this->loadedYamlConfiguration;\n        }\n\n        $reflection = new ReflectionClass(get_class($this));\n        $yamlFilePath = dirname($reflection->getFileName()).'/plugin.yaml';\n\n        if (file_exists($yamlFilePath)) {\n            $this->loadedYamlConfiguration = Yaml::parse(file_get_contents($yamlFilePath));\n\n            if (!is_array($this->loadedYamlConfiguration)) {\n                throw new SystemException(sprintf(\n                    'Invalid format of the plugin configuration file: %s. The file should define an array.',\n                    $yamlFilePath\n                ));\n            }\n        }\n        else {\n            if ($exceptionMessage !== null) {\n                throw new SystemException($exceptionMessage);\n            }\n\n            $this->loadedYamlConfiguration = [];\n        }\n\n        return $this->loadedYamlConfiguration;\n    }\n}\n","sourceCodeStart":299,"sourceCodeEnd":334,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/system/classes/PluginBase.php#L299-L334","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make plugin.yaml a proper top-level mapping (key: value lines) — the file must define an array.","If the file is intentionally empty, delete it and override pluginDetails() in the plugin class instead.","Lint the file: php -r \"var_export(Symfony\\Component\\Yaml\\Yaml::parse(file_get_contents('plugins/acme/blog/plugin.yaml')));\" must print an array."],"exampleFix":"# before — plugins/acme/blog/plugin.yaml (empty file, parses to null)\n\n# after\nplugin:\n  name: Blog\n  description: 'Blog management'\n  author: Acme\n  icon: icon-pencil","handlingStrategy":"validation","validationCode":"// Assert the yaml document parses to an array before the framework reads it\nuse Symfony\\Component\\Yaml\\Yaml;\n\nfunction pluginYamlParsesToArray(string $path): bool\n{\n    if (!file_exists($path)) return false;\n    $parsed = Yaml::parse(file_get_contents($path));\n    return is_array($parsed);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never commit an empty plugin.yaml as a placeholder — delete it and override pluginDetails() instead.","Start plugin.yaml from a known-good scaffold with the plugin: mapping present.","Lint all plugin YAML files in CI: parsed result must be an array with a plugin key."],"tags":["php","plugin","yaml","plugin-yaml","configuration"],"backgroundTag":"invalid-config-format","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}