halo-dev/halo · error · IllegalArgumentException

Provider resource path must be provider-root-relative: {reso

Error message

Provider resource path must be provider-root-relative: {resourcePath}

What it means

Error "Provider resource path must be provider-root-relative: {resourcePath}" thrown in halo-dev/halo.

Source

Thrown at application/src/main/java/run/halo/app/plugin/UiPluginBundleServiceImpl.java:256

        var resource = providerResource(candidate, resourcePath);
        if (resource == null || !resource.isReadable()) {
            throw new IllegalArgumentException(
                    "Provider resource does not exist inside its root: " + value.textValue());
        }
        return resourcePath;
    }

    private static String normalizeResourcePath(String resourcePath) {
        if (!StringUtils.hasText(resourcePath)) {
            throw new IllegalArgumentException("Provider resource path must not be blank");
        }
        var normalizedSlashes = resourcePath.replace('\\', '/');
        if (normalizedSlashes.startsWith("/")
                || normalizedSlashes.startsWith("//")
                || normalizedSlashes.contains("?")
                || normalizedSlashes.contains("#")
                || normalizedSlashes.matches("^[a-zA-Z][a-zA-Z0-9+.-]*:.*")) {
            throw new IllegalArgumentException(
                    "Provider resource path must be provider-root-relative: " + resourcePath);
        }
        var normalized = Path.of(normalizedSlashes).normalize();
        if (normalized.isAbsolute()
                || normalized.startsWith("..")
                || normalized.toString().equals(".")) {
            throw new IllegalArgumentException("Provider resource path escapes its root: " + resourcePath);
        }
        return normalized.toString().replace('\\', '/');
    }

    private UiPluginProviderDescriptor createDescriptor(String version, List<KeyedProvider> keyedProviders) {
        var hasLegacyProvider = keyedProviders.stream()
                .map(KeyedProvider::provider)
                .anyMatch(provider -> provider.kind() == ProviderKind.LEGACY);
        return new UiPluginProviderDescriptor(
                keyedProviders.stream().map(this::describeProvider).toList(),
                hasLegacyProvider ? versionedBundleUrl("bundle.js", version) : null);

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Use a path relative to the provider root (no leading '/' or absolute path) for the manifest entry/style values.
2. Rebuild the plugin with the official bundler kit, which emits root-relative paths.
3. Remove any URL or absolute filesystem path mistakenly placed in the manifest.

When it happens

Trigger: Thrown at application/src/main/java/run/halo/app/plugin/UiPluginBundleServiceImpl.java:256 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/ab6dfe62f617e4f0. Report an issue: GitHub.