halo-dev/halo · error · PluginRuntimeException

Cannot find the plugin manifest path

Error message

Cannot find the plugin manifest path

What it means

Error "Cannot find the plugin manifest path" thrown in halo-dev/halo.

Source

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

    @Override
    public Plugin find(Path pluginPath) {
        Plugin plugin = readPluginDescriptor(pluginPath);
        if (plugin.getStatus() == null) {
            Plugin.PluginStatus pluginStatus = new Plugin.PluginStatus();
            pluginStatus.setPhase(Plugin.Phase.PENDING);
            pluginStatus.setLoadLocation(pluginPath.toUri());
            plugin.setStatus(pluginStatus);
        }
        MetadataUtil.nullSafeAnnotations(plugin).put(PluginConst.PLUGIN_PATH, pluginPath.toString());
        return plugin;
    }

    protected Plugin readPluginDescriptor(Path pluginPath) {
        Path propertiesPath = null;
        try {
            propertiesPath = getManifestPath(pluginPath, propertiesFileName);
            if (propertiesPath == null) {
                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);

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Ensure the plugin is packaged as a JAR containing plugin.yaml (or plugin.yml) at its root, or provide the path to an unpacked plugin directory.
2. Verify the file being installed is actually a plugin JAR and not a corrupted or wrong file.
3. If installing from a directory, point Halo at the directory that directly contains the plugin manifest.

When it happens

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