{"record":{"id":"1c97e74c057dced6","repo":"apache/seatunnel","slug":"seatunnelapierrorcode-config-validation-failed-1c97e7","errorCode":"SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED","errorMessage":"Failed to determine whether file source path is a file or directory: %s","messagePattern":"Failed to determine whether file source path is a file or directory: (.+?)","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/source/reader/BinaryReadStrategy.java","lineNumber":66,"sourceCode":"                    new SeaTunnelDataType[] {\n                        PrimitiveByteArrayType.INSTANCE, BasicType.STRING_TYPE, BasicType.LONG_TYPE\n                    });\n\n    private String basePath;\n    private transient boolean basePathIsFile;\n    private int binaryChunkSize = FileBaseSourceOptions.BINARY_CHUNK_SIZE.defaultValue();\n    private boolean completeFileMode =\n            FileBaseSourceOptions.BINARY_COMPLETE_FILE_MODE.defaultValue();\n    private transient String lastReadFingerprint;\n\n    @Override\n    public void init(HadoopConf conf) {\n        super.init(conf);\n        basePath = pluginConfig.getString(FileBaseSourceOptions.FILE_PATH.key());\n        try {\n            basePathIsFile = hadoopFileSystemProxy.isFile(basePath);\n        } catch (IOException e) {\n            throw new FileConnectorException(\n                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,\n                    \"Failed to determine whether file source path is a file or directory: \"\n                            + basePath,\n                    e);\n        }\n\n        // Load binary chunk size configuration\n        if (pluginConfig.hasPath(FileBaseSourceOptions.BINARY_CHUNK_SIZE.key())) {\n            binaryChunkSize = pluginConfig.getInt(FileBaseSourceOptions.BINARY_CHUNK_SIZE.key());\n            // Validate chunk size - should be positive and reasonable\n            if (binaryChunkSize <= 0) {\n                throw new IllegalArgumentException(\n                        \"Binary chunk size must be positive, got: \" + binaryChunkSize);\n            }\n            if (binaryChunkSize > 100 * 1024 * 1024) { // 100MB limit\n                throw new IllegalArgumentException(\n                        \"Binary chunk size too large (max 100MB), got: \" + binaryChunkSize);\n            }","sourceCodeStart":48,"sourceCodeEnd":84,"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/source/reader/BinaryReadStrategy.java#L48-L84","documentation":"BinaryReadStrategy.init calls hadoopFileSystemProxy.isFile(basePath) to decide whether the configured path is a single file or a directory. If that check throws an IOException (filesystem unreachable, permission probe failure, HDFS NameNode error, etc.), it wraps it in a FileConnectorException with CONFIG_VALIDATION_FAILED, including the path that could not be classified.","triggerScenarios":"Initializing a binary file source whose FILE_PATH points to an HDFS/S3/local path where the isFile() metadata call fails: NameNode down, S3 endpoint unreachable, bad credentials, or network interruption.","commonSituations":"HDFS cluster unavailable; S3/OSS misconfigured endpoint or expired credentials; Kerberos/authentication issues; firewall blocking the storage service; typo causing a resolver-level failure on some filesystems.","solutions":["Inspect the wrapped 'Caused by' IOException for the root cause (connection refused, auth, timeout).","Verify storage connectivity from the SeaTunnel worker nodes (e.g. hdfs dfs -ls <path>).","Fix HadoopConf settings (fs.defaultFS, endpoint, credentials) and re-run the job."],"exampleFix":"// before\npath = \"hdfs://namenode-host:9000/data/binary\"\n// after (corrected reachable FS + valid path)\npath = \"hdfs://nn1.cluster:8020/data/binary\"","handlingStrategy":"try-catch","validationCode":"// Java, connectivity pre-check before submitting the job\norg.apache.hadoop.fs.FileSystem fs = FileSystem.get(hadoopConf);\nif (!fs.exists(new org.apache.hadoop.fs.Path(basePath))) {\n    throw new IllegalStateException(\"Path not reachable: \" + basePath);\n}","typeGuard":null,"tryCatchPattern":"try {\n    readStrategy.init(hadoopConf);\n} catch (FileConnectorException e) {\n    Throwable root = e.getCause();\n    log.error(\"Cannot classify path {}: {}\", basePath, root == null ? e : root.getMessage());\n    throw e;\n}","preventionTips":["Verify storage access (hdfs dfs -ls / aws s3 ls) from worker nodes before running.","Check fs.defaultFS, endpoints, and credentials in HadoopConf.","Monitor NameNode/storage endpoint health; add retry/backoff at the infra level."],"tags":["hadoop","filesystem","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"}