{"record":{"id":"9b064b9ff41004f2","repo":"apache/seatunnel","slug":"file-list-get-failed","errorCode":"FILE_LIST_GET_FAILED","errorMessage":"Get file list from this path [%s] failed","messagePattern":"Get file list from this path \\[(.+?)\\] failed","errorType":"error_code","errorClass":"FileConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/config/BaseFileSourceConfig.java","lineNumber":150,"sourceCode":"\n    private List<String> discoverFilePaths(ReadStrategy discoveryReadStrategy) {\n        String rootPath = baseFileSourceConfig.get(FileBaseSourceOptions.FILE_PATH);\n        long startTime = System.currentTimeMillis();\n        try {\n            List<String> discoveredFilePaths = discoveryReadStrategy.getFileNamesByPath(rootPath);\n            log.info(\n                    \"File source discovery finished: plugin={}, path={}, files={}, cost={}ms\",\n                    getPluginName(),\n                    safeDiscoveryRootContext,\n                    discoveredFilePaths.size(),\n                    System.currentTimeMillis() - startTime);\n            return discoveredFilePaths;\n        } catch (Exception ex) {\n            String errorMsg =\n                    String.format(\n                            \"Get file list from this path [%s] failed\", safeDiscoveryRootContext);\n            if (isMarkdownKnowledgeSyncMetadataEnabled(baseFileSourceConfig)) {\n                throw new FileConnectorException(\n                        FileConnectorErrorCode.FILE_LIST_GET_FAILED,\n                        errorMsg,\n                        MarkdownKnowledgeSyncMetadata.copyStackTraceOnly(ex));\n            }\n            throw new FileConnectorException(\n                    FileConnectorErrorCode.FILE_LIST_GET_FAILED, errorMsg, ex);\n        }\n    }\n\n    private CatalogTable parseCatalogTable(ReadonlyConfig readonlyConfig) {\n        final CatalogTable catalogTable = catalogTableFromConfig;\n        boolean configSchema =\n                readonlyConfig.getOptional(ConnectorCommonOptions.SCHEMA).isPresent();\n        if (CollectionUtils.isEmpty(filePaths)) {\n            // When there are no files (including sync_mode=update filtered all files), choose a\n            // compatible schema so that downstream can initialize correctly.\n            if (fileFormat == FileFormat.BINARY\n                    || fileFormat == FileFormat.MARKDOWN","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/config/BaseFileSourceConfig.java#L132-L168","documentation":"BaseFileSourceConfig.discoverFilePaths wraps any exception raised while listing files under a configured source path into FileConnectorException with code FILE_LIST_GET_FAILED, using the safe discovery root path as context. This non-Markdown branch attaches the original exception as the cause.","triggerScenarios":"Any Exception during file discovery (directory does not exist, HDFS/S3/OSS connection failure, permission denied, invalid glob) inside discoverFilePaths, called from getFilePathsForSplitEnumerator or recursively via discoverFilePaths.","commonSituations":"Typos or wrong scheme in the source 'path' config; Hadoop/S3 credentials missing or expired; path is a file not a directory; network unreachable from the cluster nodes; regex/path patterns matching nothing or failing.","solutions":["Verify the configured source path exists and is accessible from the job's execution nodes (test with hadoop fs -ls or the storage CLI).","Fix the path scheme/typos and ensure the filesystem plugin (hdfs-s3/oss, etc.) and credentials (access keys, kerberos, tokens) are correctly configured.","Check filesystem permissions for the SeaTunnel runtime user.","Inspect the caused-by exception in the stack trace for the underlying reason (connection refused, auth error, etc.)."],"exampleFix":"// before\npath = \"/user/seatunnel/data/*.csv\"  // path missing on cluster\n// after (verified path)\npath = \"/user/seatunnel/dataset/*.csv\"  # exists and readable on all nodes","handlingStrategy":"validation","validationCode":"// Pre-flight: verify the path is listable before submitting the job\nFileSystem fs = FileSystem.get(new Path(sourcePath).toUri(), hadoopConf);\nif (!fs.exists(new Path(sourcePath))) {\n    throw new IllegalArgumentException(\"Source path does not exist: \" + sourcePath);\n}\nif (!fs.getFileStatus(new Path(sourcePath)).isDirectory()) {\n    throw new IllegalArgumentException(\"Source path is not a directory: \" + sourcePath);\n}","typeGuard":null,"tryCatchPattern":"try {\n    enumerator discovery = sourceConfig.discoverFilePaths(...);\n} catch (FileConnectorException e) {\n    if (FileConnectorErrorCode.FILE_LIST_GET_FAILED.equals(e.getSeaTunnelErrorCode())) {\n        throw new IllegalStateException(\"Check source path/credentials: \" + e.getCause(), e);\n    }\n    throw e;\n}","preventionTips":["Validate path existence and scheme (hdfs://, s3://, local) on all worker nodes before submitting.","Run hadoop fs -ls / storage CLI with the same credentials the job uses.","Keep Hadoop/S3 credentials and filesystem plugins installed and up to date on the cluster.","Use relative-free, absolute, verified paths in configs."],"tags":["file-connector","file-listing","io"],"backgroundTag":"file-read-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}