apache/seatunnel · error · IOException

Failed during target_bulk_listing for path=%s

Error message

Failed during target_bulk_listing for path=%s

What it means

UpdateFileMetadataLoader.load performs a bulk status lookup on target (destination) directories to detect which files already exist; an IOException other than FileNotFoundException is rethrown as 'Failed during target_bulk_listing for path=...'. The path is masked for logging. It means the bulk metadata listing against the target filesystem failed.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/reader/UpdateFileMetadataLoader.java:104

                for (Map.Entry<Path, List<Request>> group : bulkGroups) {
                    long started = System.nanoTime();
                    Map<String, Request> wanted = new HashMap<>();
                    for (Request request : group.getValue()) {
                        wanted.put(new Path(request.targetPath).getName(), request);
                    }
                    try {
                        session.list(
                                group.getKey(),
                                status -> {
                                    Request request = wanted.get(status.getPath().getName());
                                    if (request != null) {
                                        ordered[request.order] = status;
                                    }
                                });
                    } catch (FileNotFoundException ignored) {
                        // A missing target directory means every source file in the group is new.
                    } catch (IOException e) {
                        throw new IOException(
                                "Failed during target_bulk_listing for path="
                                        + mask(group.getKey()),
                                e);
                    } finally {
                        bulkNanos += System.nanoTime() - started;
                    }
                }
            }
        }

        PointResult pointResult = loadPoints(pointRequests, target, ordered, parallelism);
        return new Result(
                Arrays.asList(ordered),
                bulkGroups.size(),
                pointRequests.size(),
                pointResult.peakConcurrency,
                pointResult.peakInFlight,
                bulkNanos,

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check target storage health/connectivity from worker nodes and retry the job
2. Inspect the cause chain for the storage-specific error (throttling, auth, timeout) and address it (backoff, IAM/Kerberos credentials)
3. Lower listing concurrency or add retry/backoff if object storage rate-limits
4. Verify target path permissions are readable

Example fix

// before
// job failing on S3 503 during bulk listing
// after
// enable S3 requester retry/backoff or reduce parallelism, then rerun the sync job

// probe target listing before starting the job
try {
    fs.listStatus(targetPath);
} catch (IOException e) {
    throw new IllegalStateException("Target filesystem unhealthy before job: " + targetPath, e);
}

try {
    loader.load(requests);
} catch (IOException e) {
    if (e.getMessage().startsWith("Failed during target_bulk_listing")) {
        // retry with backoff; check cause for throttling/auth
        retryWithBackoff(e, 3);
    } else throw e;
}

When it happens

Trigger: Listing a target directory whose storage backend throws IOException: HDFS NameNode unreachable, S3 throttling (HTTP 5xx), token/credential expiry, or transient network errors. (Missing target directory is explicitly tolerated as 'all files new'.)

Common situations: Incremental/append sync jobs where the destination storage is degraded; throttled object storage under high listing concurrency; expired Kerberos/STS credentials mid-job.

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

• FILE_LIST_GET_FAILED
• Target metadata lookup failed for path=%s
• Checking catalog path %s exists exception.
• Failed to list files from names${path}
• Failed to read checkpoint data, file name is ${fileName},job

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