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.

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)

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.