{"record":{"id":"071907582b9b10bf","repo":"octobercms/october","slug":"plugin-configuration-file-plugin-yaml-is-not-found","errorCode":null,"errorMessage":"Plugin configuration file plugin.yaml is not found for the plugin class %s. Create the file or override pluginDetails() method in the plugin class.","messagePattern":"Plugin configuration file plugin\\.yaml is not found for the plugin class (.+?)\\. Create the file or override pluginDetails\\(\\) method in the plugin class\\.","errorType":"exception","errorClass":"SystemException","httpStatus":null,"severity":"error","filePath":"modules/system/classes/PluginBase.php","lineNumber":325,"sourceCode":"            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":307,"sourceCodeEnd":334,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/system/classes/PluginBase.php#L307-L334","documentation":"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.","triggerScenarios":"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 [].","commonSituations":"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.","solutions":["Create plugin.yaml in the plugin root (same directory as Plugin.php) with a top-level array containing plugin, name, description, author, icon keys","Or override pluginDetails(): array in your Plugin class and return the details array directly, bypassing the yaml lookup","Check the exact filename casing and extension: it must be lowercase 'plugin.yaml', not plugin.yml or Plugin.yaml","Verify the file actually deployed to the server (rsync/git archive exclusions) and clear cached plugin metadata if present"],"exampleFix":"// before — plugin has no plugin.yaml and relies on the default pluginDetails()\nclass Plugin extends \\System\\Classes\\PluginBase\n{\n}\n// after — override pluginDetails() so the yaml file is not required\nclass Plugin extends \\System\\Classes\\PluginBase\n{\n    public function pluginDetails(): array\n    {\n        return [\n            'name' => 'My Plugin',\n            'description' => 'Adds features.',\n            'author' => 'Me',\n            'icon' => 'icon-leaf',\n        ];\n    }\n}","handlingStrategy":"validation","validationCode":"// Before relying on plugin.yaml, confirm it ships with the plugin\n$pluginFile = (new ReflectionClass(\\My\\Plugin\\Plugin::class))->getFileName();\n$hasYaml = file_exists(dirname($pluginFile) . '/plugin.yaml');\nif (!$hasYaml && !method_exists(\\My\\Plugin\\Plugin::class, 'pluginDetails')) {\n    // details lookup will throw — create the yaml or add pluginDetails() before enabling\n}","typeGuard":null,"tryCatchPattern":"try {\n    $details = \\System\\Classes\\PluginManager::instance()->findByIdentifier('Author.Plugin')->pluginDetails();\n} catch (\\System\\Classes\\SystemException $ex) {\n    // plugin.yaml missing and no pluginDetails() override — degrade to defaults\n    $details = ['name' => 'Author.Plugin', 'description' => ''];\n}","preventionTips":["Always ship plugin.yaml with the plugin skeleton, or always override pluginDetails() — pick one convention per team","Add plugin.yaml to the plugin's test fixture so CI catches a missing file","Check deploy artifacts (git archive/rsync excludes) include *.yaml in plugin directories"],"tags":["octobercms","plugin","yaml","config","missing-file"],"backgroundTag":"missing-config-file","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}