halo-dev/halo · error · PluginRuntimeException

Unable to find plugin descriptor file '{}'

Error message

Unable to find plugin descriptor file '{}'

What it means

Error "Unable to find plugin descriptor file '{}'" thrown in halo-dev/halo.

Source

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

                throw new PluginRuntimeException("Cannot find the plugin manifest path");
            }

            log.debug("Lookup plugin descriptor in '{}'", propertiesPath);
            if (Files.notExists(propertiesPath)) {
                throw new PluginRuntimeException("Cannot find '{}' path", propertiesPath);
            }
            Resource propertyResource = new FileSystemResource(propertiesPath);
            return unstructuredToPlugin(propertyResource);
        } finally {
            FileUtils.closePath(propertiesPath);
        }
    }

    protected Plugin unstructuredToPlugin(Resource propertyResource) {
        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 {

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Add a plugin.yaml (or plugin.yml) descriptor file at the root of the plugin JAR or directory.
2. Rebuild the plugin with the Halo plugin Gradle/Maven tooling so the descriptor is generated and packaged.
3. Check that the descriptor file name matches exactly (plugin.yaml), including case.

When it happens

Trigger: Thrown at application/src/main/java/run/halo/app/plugin/YamlPluginFinder.java:99 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/601889d79765c42c. Report an issue: GitHub.