halo-dev/halo · error · PluginRuntimeException

Unable to find plugin descriptor file: plugin.yaml

Error message

Unable to find plugin descriptor file: plugin.yaml

What it means

Error "Unable to find plugin descriptor file: plugin.yaml" thrown in halo-dev/halo.

Source

Thrown at application/src/main/java/run/halo/app/plugin/YamlPluginFinder.java:114

        YamlUnstructuredLoader yamlUnstructuredLoader = new YamlUnstructuredLoader(propertyResource);
        List<Unstructured> unstructuredList = yamlUnstructuredLoader.load();
        if (unstructuredList.size() != 1) {
            throw new PluginRuntimeException("Unable to find plugin descriptor file '{}'", propertiesFileName);
        }
        Unstructured unstructured = unstructuredList.get(0);
        return Unstructured.OBJECT_MAPPER.convertValue(unstructured, Plugin.class);
    }

    protected Path getManifestPath(Path pluginPath, String propertiesFileName) {
        if (Files.isDirectory(pluginPath)) {
            for (String location : PLUGIN_CLASSPATH.getClassesDirectories()) {
                var path = pluginPath.resolve(location).resolve(propertiesFileName);
                Resource propertyResource = new FileSystemResource(path);
                if (propertyResource.exists()) {
                    return path;
                }
            }
            throw new PluginRuntimeException("Unable to find plugin descriptor file: " + DEFAULT_PROPERTIES_FILE_NAME);
        } else {
            // it's a jar file
            try {
                return FileUtils.getPath(pluginPath, propertiesFileName);
            } catch (IOException e) {
                throw new PluginRuntimeException(e);
            }
        }
    }
}

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Place a plugin.yaml file at the root of the plugin archive or development directory.
2. If developing locally, run the plugin build so plugin.yaml is generated from the build configuration.
3. Verify the plugin path passed to Halo is the plugin root, not a subdirectory.

When it happens

Trigger: Thrown at application/src/main/java/run/halo/app/plugin/YamlPluginFinder.java:114 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of halo-dev/halo@d2f5165f9c (2026-08-14). Data as JSON: /api/errors/9114555ce2aa7517. Report an issue: GitHub.