apache/seatunnel · error · ConfigCheckException

Invalid plugin dependency path: ${uri}

Error message

Invalid plugin dependency path: ${uri}

What it means

toUrl converts a plugin dependency's java.net.URI into a URL and throws ConfigCheckException('Invalid plugin dependency path: <uri>') when URI.toURL() fails, i.e. the URI is not convertible to a valid URL (bad scheme/malformed path).

Source

Thrown at seatunnel-core/seatunnel-core-starter/src/main/java/org/apache/seatunnel/core/starter/utils/ConfigValidationUtils.java:200

                        .collect(Collectors.toList()));
        additionalJars = additionalJars.stream().distinct().collect(Collectors.toList());
        if (additionalJars.isEmpty()) {
            return parentClassLoader;
        }

        try {
            ADD_URL_TO_CLASSLOADER.accept(parentClassLoader, additionalJars);
            return parentClassLoader;
        } catch (RuntimeException e) {
            return new URLClassLoader(additionalJars.toArray(new URL[0]), parentClassLoader);
        }
    }

    private static URL toUrl(java.net.URI uri) {
        try {
            return uri.toURL();
        } catch (Exception e) {
            throw new ConfigCheckException("Invalid plugin dependency path: " + uri, e);
        }
    }

    private static void validateEnvironmentConfig(Config config) {
        if (!config.hasPath(Constants.ENV)) {
            return;
        }
        ReadonlyConfig envConfig = ReadonlyConfig.fromConfig(config.getConfig(Constants.ENV));
        OptionRule optionRule = new EnvOptionRule().optionRule();
        validateOptionTypes(envConfig, optionRule);
        org.apache.seatunnel.api.configuration.util.ConfigValidator.of(envConfig)
                .validate(optionRule);
    }

    private static void validateOptionTypes(ReadonlyConfig config, OptionRule rule) {
        for (Option<?> option : rule.getOptionalOptions()) {
            config.getOptional(option);
        }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Fix the dependency path in the config to a well-formed absolute URL/file URI
  2. Escape or remove spaces/special characters from the path
  3. Verify the referenced jar exists; use forward slashes and a file:/ scheme

Example fix

// before
env { plugin_dependencies = ["/opt/my plugin/lib.jar"] }
// after
env { plugin_dependencies = ["file:/opt/my%20plugin/lib.jar"] }
Defensive patterns

Strategy: validation

Validate before calling

try { new java.net.URI(depPath); } catch (URISyntaxException e) { throw new IllegalArgumentException("Bad plugin dependency path: " + depPath); }

Try / catch

try { ConfigValidationUtils.validate(config); } catch (ConfigCheckException e) { if (e.getMessage().startsWith("Invalid plugin dependency path")) { log.error("Fix plugin_dependencies: {}", e.getMessage()); } }

Prevention

When it happens

Trigger: A plugin-dependency entry in the env/job config (e.g. pluginJar paths or 'add' URLs) contains a malformed URI such as missing scheme, illegal characters, or an unresolvable path spec.

Common situations: Typos in plugin dependency paths, relative paths with spaces or Windows-style backslashes, or referencing jars that were never installed.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/625c033bd64815ed. Report an issue: GitHub.