apache/seatunnel · error · FileConnectorException

FILE_LIST_GET_FAILED

FILE_LIST_GET_FAILED

Error message

Get file list from this path [%s] failed, caused by: %s

What it means

parseFilePaths resolves the Hive table location(s) into a concrete HDFS file list. If the filesystem listing of the target path throws (path missing, NameNode unreachable, permission denied), the exception is wrapped in a FileConnectorException with FILE_LIST_GET_FAILED, including the path and an exception summary.

Source

Thrown at seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/source/config/HiveSourceConfig.java:231

        readonlyConfig
                .getOptional(HiveSourceOptions.REMOTE_USER)
                .ifPresent(hadoopConf::setRemoteUser);
        return hadoopConf;
    }

    private List<String> parseFilePaths(Table table, ReadStrategy readStrategy) {
        String hdfsPath = parseHdfsPath(table);
        try {
            return readStrategy.getFileNamesByPath(hdfsPath);
        } catch (IOException e) {
            if (isFileNotFound(e)) {
                return Collections.emptyList();
            }
            String errorMsg =
                    String.format(
                            "Get file list from this path [%s] failed, caused by: %s",
                            hdfsPath, getExceptionSummary(e));
            throw new FileConnectorException(
                    FileConnectorErrorCode.FILE_LIST_GET_FAILED, errorMsg, e);
        }
    }

    private static String getExceptionSummary(Throwable throwable) {
        String message = throwable.getMessage();
        if (StringUtils.isBlank(message)) {
            return throwable.getClass().getName();
        }
        return throwable.getClass().getName() + ": " + message;
    }

    private static boolean isFileNotFound(Throwable throwable) {
        Throwable current = throwable;
        while (current != null) {
            if (current instanceof FileNotFoundException
                    || current instanceof NoSuchFileException
                    || current instanceof PathNotFoundException) {

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Verify the path exists: `hdfs dfs -ls <path>` with the same user that runs the SeaTunnel job
  2. Check the HDFS config files (core-site.xml, hdfs-site.xml) are on the classpath and point to the right NameNode
  3. Fix permissions: grant the job user read+execute on the directory (`hdfs dfs -chmod` or correct ACLs), or run as an authorized principal
  4. Read the 'caused by' summary in the message to distinguish connection failure vs permission vs missing path
  5. For cloud locations, verify endpoint/credentials for s3a/oss prefixes

Example fix

// before (table location removed)
result_path = "hdfs://namenode:8020/warehouse/db.db/sales"   // directory deleted
// after (recreate/point at existing data)
result_path = "hdfs://namenode:8020/warehouse/db.db/sales"  // after `hdfs dfs -ls` confirms it exists
// or fix URI:
// before: hdfs://nn-old:8020/...  -> after: hdfs://nn-active:8020/...
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight listing as the job user:
// hdfs dfs -ls hdfs://namenode:8020/warehouse/db.db/table >/dev/null && echo OK

Try / catch

try {
    HiveSourceConfig cfg = new HiveSourceConfig(pluginConfig);
} catch (FileConnectorException e) {
    if (e.getCode().equals(FileConnectorErrorCode.FILE_LIST_GET_FAILED)) {
        // inspect path + cause: fix URI, permissions, or NameNode connectivity
    }
    throw e;
}

Prevention

When it happens

Trigger: HiveSourceConfig construction when the table's HDFS location cannot be listed: nonexistent directory, HDFS NameNode down/wrong fs.defaultFS, or the submitting user lacks read permission on the path.

Common situations: Table directory dropped/renamed after partition deletes; misconfigured HDFS URI or missing core-site/hdfs-site configs; Kerberos/HDFS permission denied for the job user; cloud storage path (s3a/oss) with wrong credentials.

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