apache/seatunnel · error · RuntimeException

the uri of jar illegal

Error message

the uri of jar illegal:${uri}

What it means

FlinkExecution.registerPlugin resolves local jar paths from env 'jars' into URIs and converts each to a URL for the classloader; a URI that cannot be converted to a URL triggers a RuntimeException 'the uri of jar illegal:<uri>'.

Solutions

1. Use absolute paths for every entry in env.jars
2. Verify each jar file exists at the given path before starting the job
3. Move SeaTunnel/Flink installations to a path without spaces or special characters
4. Check that the paths are proper file URIs (file:/...) not raw malformed strings

Example fix

// before
env {
  jars = "connector/mysql-connector.jar"
}
// after
env {
  jars = "/opt/seatunnel/connectors/mysql-connector.jar"
}

for (String jar : jars.split(";")) {
    Path p = java.nio.file.Paths.get(jar);
    if (!p.isAbsolute() || !java.nio.file.Files.exists(p)) {
        throw new IllegalArgumentException("Invalid jar path: " + jar);
    }
}

boolean isValidJarUri(Path p) {
    try { p.toUri().toURL(); return true; } catch (Exception e) { return false; }
}

try {
    registerPlugin(envConfig);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("the uri of jar illegal")) {
        log.error("Fix env.jars entries to absolute, valid paths", e);
    }
}

When it happens

Trigger: env config lists jars entries whose Path.toUri().toURL() fails due to malformed or non-absolute paths, e.g. relative paths or paths with characters that make the URI unresolvable.

Common situations: Relative jar paths in env.jars (should be absolute); jars directory moved or deleted; spaces or special characters in the SeaTunnel install path.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• load flink starter error.
• Remove invalid jar when inject jars into config
• the uri of jar illegal
• All candidate sink tables were skipped in Flink starter.
• All candidate sink tables were skipped in Flink starter.

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

Appendix: source

Thrown at seatunnel-core/seatunnel-flink-starter/seatunnel-flink-starter-common/src/main/java/org/apache/seatunnel/core/starter/flink/execution/FlinkExecution.java:189

    private void registerPlugin(Config envConfig) {
        List<Path> thirdPartyJars = new ArrayList<>();
        if (envConfig.hasPath(EnvCommonOptions.JARS.key())) {
            thirdPartyJars =
                    new ArrayList<>(
                            Common.getThirdPartyJars(
                                    envConfig.getString(EnvCommonOptions.JARS.key())));
        }
        thirdPartyJars.addAll(Common.getPluginsJarDependenciesWithoutConnectorDependency());
        List<URL> jarDependencies =
                Stream.concat(thirdPartyJars.stream(), Common.getLibJars().stream())
                        .map(Path::toUri)
                        .map(
                                uri -> {
                                    try {
                                        return uri.toURL();
                                    } catch (MalformedURLException e) {
                                        throw new RuntimeException(
                                                "the uri of jar illegal:" + uri, e);
                                    }
                                })
                        .collect(Collectors.toList());
        FlinkAbstractPluginExecuteProcessor.ADD_URL_TO_CLASSLOADER.accept(
                Thread.currentThread().getContextClassLoader(), jarDependencies);
        jarPaths.addAll(jarDependencies);
    }

    private Config registerPlugin(Config config, Collection<URL> jars) {
        config =
                this.injectJarsToConfig(
                        config, ConfigUtil.joinPath("env", "pipeline", "jars"), jars);
        return this.injectJarsToConfig(
                config, ConfigUtil.joinPath("env", "pipeline", "classpaths"), jars);
    }

    private Config injectJarsToConfig(Config config, String path, Collection<URL> jars) {

View on GitHub (pinned to cf67b549a7)