halo-dev/halo · error · PluginDependencyException.CyclicException

https://halo.run/probs/plugin-cyclic-dependency

https://halo.run/probs/plugin-cyclic-dependency

Error message

A cyclic dependency was detected.

What it means

Error "A cyclic dependency was detected." thrown in halo-dev/halo.

Source

Thrown at application/src/main/java/run/halo/app/plugin/PluginServiceImpl.java:183

                                    // Disable auto enable after installation
                                    p.getSpec().setEnabled(false);
                                })
                                .flatMap(client::create))));
    }

    private void checkDependencies(Plugin plugin) {
        var resolvedPlugins = new ArrayList<>(pluginManager.getResolvedPlugins());
        var pluginDescriptors = new ArrayList<PluginDescriptor>(resolvedPlugins.size() + 1);

        resolvedPlugins.stream().map(PluginWrapper::getDescriptor).forEach(pluginDescriptors::add);

        var pluginDescriptor = YamlPluginDescriptorFinder.convert(plugin);
        pluginDescriptors.add(pluginDescriptor);

        var deptResolver = new DependencyResolver(pluginManager.getVersionManager());
        var result = deptResolver.resolve(pluginDescriptors);
        if (result.hasCyclicDependency()) {
            throw new PluginDependencyException.CyclicException();
        }
        var notFoundDependencies = result.getNotFoundDependencies();
        if (!CollectionUtils.isEmpty(notFoundDependencies)) {
            throw new PluginDependencyException.NotFoundException(notFoundDependencies);
        }

        var wrongVersionDependencies = result.getWrongVersionDependencies();
        if (!CollectionUtils.isEmpty(wrongVersionDependencies)) {
            throw new PluginDependencyException.WrongVersionsException(wrongVersionDependencies);
        }
    }

    @Override
    public Mono<Plugin> upgrade(String name, Path path) {
        return findPluginManifest(path)
                .doOnNext(plugin -> {
                    satisfiesRequiresVersion(plugin);
                    checkDependencies(plugin);

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Inspect the plugin dependency graph: two or more plugins declare dependencies on each other (directly or transitively).
2. Edit the plugin.yaml 'dependsOn' declarations of the involved plugins to remove the cycle, then rebuild and reinstall the plugins.
3. Use the dependency list reported in the error to find which plugins form the cycle and break it at the least important edge.

When it happens

Trigger: Thrown at application/src/main/java/run/halo/app/plugin/PluginServiceImpl.java:183 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/80d5d278a51fa3e3. Report an issue: GitHub.