halo-dev/halo · error · UnsatisfiedAttributeValueException

problemDetail.plugin.version.unsatisfied.requires

problemDetail.plugin.version.unsatisfied.requires

Error message

Plugin requires a minimum system version of [%s], but the current version is [%s].

What it means

Error "Plugin requires a minimum system version of [%s], but the current version is [%s]." thrown in halo-dev/halo.

Source

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

                    plugin.getStatus().setLoadLocation(loadLocation.toUri());
                    var annotations = plugin.getMetadata().getAnnotations();
                    if (annotations == null) {
                        annotations = new HashMap<>();
                        plugin.getMetadata().setAnnotations(annotations);
                    }
                    annotations.put(PluginConst.PLUGIN_PATH, loadLocation.toString());
                });
    }

    private void satisfiesRequiresVersion(Plugin newPlugin) {
        Assert.notNull(newPlugin, "The plugin must not be null.");
        Version version = systemVersion.get();
        // validate the plugin version
        // only use the nominal system version to compare, the format is like MAJOR.MINOR.PATCH
        String systemVersion = version.toStableVersion().toString();
        String requires = newPlugin.getSpec().getRequires();
        if (!VersionUtils.satisfiesRequires(systemVersion, requires)) {
            throw new UnsatisfiedAttributeValueException(
                    String.format(
                            "Plugin requires a minimum system version of [%s], but the current version is " + "[%s].",
                            requires, systemVersion),
                    "problemDetail.plugin.version.unsatisfied.requires",
                    new String[] {requires, systemVersion});
        }
    }

    private Flux<PresetPlugin> getPresetPlugins() {
        var resolver = new PathMatchingResourcePatternResolver();
        try {
            var presetPluginOptions = loadPresetPluginOptions(resolver);
            var resources = resolver.getResources(PRESETS_LOCATION_PATTERN);
            return Flux.fromArray(resources).mapNotNull(resource -> {
                var filename = resource.getFilename();
                if (StringUtils.isBlank(filename)) {
                    return null;
                }

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Upgrade Halo to at least the minimum version required by the plugin (the first version shown in the message).
2. Or install an older version of the plugin whose 'requires' constraint matches the current Halo version.
3. Plugin developers: verify the 'spec.requires' field in plugin.yaml is not set higher than intended.

When it happens

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