apache/seatunnel · error · FileConnectorException

FILE_READ_FAILED

FILE_READ_FAILED

Error message

Read data from this file [%s] failed

What it means

Wraps any exception thrown while reading a file's data into FILE_READ_FAILED. When pollNext() reads rows from a split and the underlying read strategy throws, the reader reports the source file (via safeSourceContext, falling back to the raw path) and copies the original stack trace as the cause. It is a generic read failure envelope, so diagnose via the cause.

Source

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

                                    + split.getTableId()
                                    + "]");
                }
                try {
                    readStrategy.read(split, output);
                } catch (Exception e) {
                    boolean markdownKnowledgeSyncMetadataEnabled =
                            markdownKnowledgeSyncMetadataTableIds.contains(split.getTableId());
                    String sourceContext = split.splitId();
                    Throwable cause = e;
                    if (markdownKnowledgeSyncMetadataEnabled) {
                        sourceContext =
                                MarkdownKnowledgeSyncMetadata.safeSourceContext(
                                        split.getFilePath());
                        cause = MarkdownKnowledgeSyncMetadata.copyStackTraceOnly(e);
                    }
                    String errorMsg =
                            String.format("Read data from this file [%s] failed", sourceContext);
                    throw new FileConnectorException(FILE_READ_FAILED, errorMsg, cause);
                }
            }
        }

        if (split != null) {
            if (Boundedness.UNBOUNDED.equals(context.getBoundedness())) {
                ReadStrategy readStrategy = readStrategyMap.get(split.getTableId());
                SourceEvent event =
                        new FileSplitFinishedEvent(
                                split.splitId(),
                                readStrategy == null
                                        ? null
                                        : readStrategy.getLastReadFingerprint());
                context.sendSourceEventToEnumerator(event);
            }
            return;
        }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the 'cause' stack trace in the exception to find the root failure (IO, parse, schema).
  2. Verify the file at the path in the message is readable and not truncated (checksum/size check).
  3. Fix the offending record or align the configured schema with the file content.
  4. For transient storage/network errors, enable restart/retry of the job.

Example fix

// before: unreadable file in path
// after: verify access and file integrity before job
hdfs dfs -test -e /data/file.json && hdfs dfs -cat /data/file.json | head
Defensive patterns

Strategy: try-catch

Validate before calling

// precheck file readability before job
hdfs dfs -test -e <path> && hdfs dfs -cat <path> | head -1

Try / catch

try { reader.pollNext(); } catch (FileConnectorException e) { if (e.getErrorCode() == FILE_READ_FAILED) { log.error("File read failed: {} — root cause:", e.getMessage(), e.getCause()); } throw e; }

Prevention

When it happens

Trigger: Any exception inside the per-split read loop in pollNext(); e.g. deserialization errors, corrupted files, IO errors, or schema mismatches surfaced by the strategy's read() call.

Common situations: Files truncated or corrupted in object storage; permission/IO errors on the underlying filesystem; a record failing schema validation; transient network failure reading from HDFS/S3.

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/6a77bb96381598db. Report an issue: GitHub.