apache/seatunnel · error · ClassLoaderException

NOT_FOUND_JAR

NOT_FOUND_JAR

Error message

The jar file %s can not be found in node %s, please ensure that the deployment paths of SeaTunnel on different nodes are consistent.

What it means

DefaultClassLoaderService.getClassLoader validates that each jar URL referenced by a job's connector-jar list physically exists on the node before building a class loader, throwing ClassLoaderException with code NOT_FOUND_JAR when a file is missing. Because Zeta runs on multiple nodes, it checks the local node and hints that SeaTunnel deployment paths must be consistent across the cluster.

Solutions

  1. Ensure the referenced jar exists at the exact same absolute path on every Zeta node (install SeaTunnel under an identical path cluster-wide).
  2. Re-upload the connector jar via the addConnectorJar API so the engine distributes it instead of referencing a local file path.
  3. Verify each node's SEATUNNEL_HOME and shared-storage mounts, or set skip-check-jar env (SKIP_CHECK_JAR=true) only as a temporary diagnostic workaround.
  4. Correct the jar path in the job configuration to point at a real file (ls the path on each node to confirm).

Example fix

// before
String jarPath = "/home/alice/seatunnel/connectors/connector-jdbc-2.3.8.jar";
// after
String jarPath = "/opt/seatunnel/connectors/connector-jdbc-2.3.8.jar"; // same on all nodes
Defensive patterns

Strategy: validation

Validate before calling

for (URL jar : jars) {
    if (!new File(jar.toURI().getPath()).exists())
        throw new IllegalStateException("jar missing on this node: " + jar);
}
// additionally verify on every worker via ssh: test -f <path>

Try / catch

try { jobClient.executeJob(); } catch (ClassLoaderException e) { if (e.getErrorCode() == ClassLoaderErrorCode.NOT_FOUND_JAR) { /* redeploy jar to all nodes or use addConnectorJar */ } throw e; }

Prevention

When it happens

Trigger: Submitting a job with jar URLs (connector jar add/delete API or 'jar' config) whose paths don't exist on some/all Zeta nodes — typically during testPreCheckJar of a job that references connectors by absolute path.

Common situations: SeaTunnel installed at different paths on different cluster nodes; jar uploaded to only the node receiving the submit request; typo or wrong user/home directory in the jar path; NFS/storage not mounted on a worker.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors


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

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-core/src/main/java/org/apache/seatunnel/engine/core/classloader/DefaultClassLoaderService.java:82

        if (!classLoaderCache.containsKey(jobId)) {
            classLoaderCache.put(jobId, new ConcurrentHashMap<>());
            classLoaderReferenceCount.put(jobId, new ConcurrentHashMap<>());
        }
        Map<String, ClassLoader> classLoaderMap = classLoaderCache.get(jobId);
        String key = covertJarsToKey(jars);
        if (classLoaderMap.containsKey(key)) {
            classLoaderReferenceCount.get(jobId).get(key).incrementAndGet();
            return classLoaderMap.get(key);
        } else {
            if (Objects.nonNull(nodeEngine)
                    && !Boolean.parseBoolean(
                            System.getenv().getOrDefault(SKIP_CHECK_JAR, "false"))) {
                for (URL jar : jars) {
                    File file = new File(jar.toURI().getPath());
                    if (!file.exists()) {
                        String host =
                                ((NodeEngineImpl) nodeEngine).getNode().getThisAddress().getHost();
                        throw new ClassLoaderException(
                                ClassLoaderErrorCode.NOT_FOUND_JAR,
                                "The jar file "
                                        + jar
                                        + " can not be found in node "
                                        + host
                                        + ", please ensure that the deployment paths of SeaTunnel on different nodes are consistent.");
                    }
                }
            } else {
                log.debug("Run the test class without file checking");
            }
            ClassLoader classLoader = new SeaTunnelChildFirstClassLoader(jars);
            log.info("Create classloader for job {} with jars {}", jobId, jars);
            classLoaderMap.put(key, classLoader);
            classLoaderReferenceCount.get(jobId).put(key, new AtomicInteger(1));
            return classLoader;
        }
    }

View on GitHub (pinned to cf67b549a7)