apache/seatunnel · error · java.lang.IllegalArgumentException

Circular condition chain detected: '%s' already exists in th

Error message

Circular condition chain detected: '%s' already exists in the chain

What it means

FileDiscoveryScanner.scan stats the root path via session.getFileStatus(root) to begin source listing. If that filesystem operation throws IOException, it is rethrown wrapped as "Failed during source_listing root_stat for protocol=..., path=..." with the path masked (sensitive parts hidden), preserving the cause. This means the connector could not even inspect the root directory of the source listing.

Source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/util/Condition.java:117

    }

    public Condition<T> and(Condition<?> next) {
        addCondition(true, next);
        return this;
    }

    public Condition<T> or(Condition<?> next) {
        addCondition(false, next);
        return this;
    }

    private void addCondition(boolean and, Condition<?> next) {
        Condition<?> cur = next;
        while (cur != null) {
            Condition<?> self = this;
            while (self != null) {
                if (self == cur) {
                    throw new IllegalArgumentException(
                            "Circular condition chain detected: '"
                                    + cur.option.key()
                                    + "' already exists in the chain");
                }
                self = self.next;
            }
            cur = cur.next;
        }
        Condition<?> tail = getTailCondition();
        tail.and = and;
        tail.next = next;
    }

    protected int getCount() {
        int i = 1;
        Condition<?> cur = this;
        while (cur.hasNext()) {
            i++;

View on GitHub (pinned to cf67b549a7)

Solutions

Verify the root path exists and is accessible: run a ls/stat against it with the same credentials the SeaTunnel worker uses.
Check the wrapped cause (getCause) for the real error — FileNotFoundException vs permission vs connectivity — and fix accordingly.
Validate storage credentials/endpoint configuration (e.g. fs.defaultFS, S3 access keys) and network reachability from worker nodes.
Add a pre-flight existence check for the root path before submitting the job.

Example fix

// before
path = "hdfs://namenode:8020/data/source"   // dir does not exist
// after
# hdfs dfs -mkdir -p /data/source  (or correct the path)
path = "hdfs://namenode:8020/data/source"

Defensive patterns

Strategy: try-catch

Validate before calling

java
org.apache.hadoop.fs.Path root = new org.apache.hadoop.fs.Path(configuredPath);
FileSystem fs = root.getFileSystem(conf);
if (!fs.exists(root)) {
    throw new IllegalArgumentException("Source root path does not exist: " + root);
}
fs.getFileStatus(root); // fail fast on permission/credentials issues

Try / catch

java
try {
    scanner.scan(session, root, filter, consumer);
} catch (IOException e) {
    if (e.getMessage().startsWith("Failed during source_listing root_stat")) {
        LOG.error("Cannot stat source root (check path exists, credentials, connectivity): "
            + e.getMessage(), e.getCause());
    }
}

Prevention

Pre-flight check that the root path exists with the worker's credentials
Validate fs.defaultFS / S3 endpoint and credential configuration before job submission
Inspect e.getCause() to distinguish not-found vs permission vs network failures
Ensure the path is not deleted between job config and execution

When it happens

Trigger: Calling scan where session.getFileStatus(root) throws IOException — the root path does not exist on the filesystem (HDFS/S3/local), credentials are missing/invalid, NameNode/endpoint is unreachable, or permission is denied on the root.

Common situations: Typo in the configured path or bucket; S3/HDFS credentials not present on the worker; cluster/network partition making the storage endpoint unreachable; path deleted between job configuration and execution.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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