{"record":{"id":"eae4ac6ee10fbee4","repo":"apache/seatunnel","slug":"failed-during-source-listing-setup-scan-for-protoc","errorCode":null,"errorMessage":"Failed during source_listing setup/scan for protocol=%s, path=%s","messagePattern":"Failed during source_listing setup/scan for protocol=(.+?), path=(.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/reader/AbstractReadStrategy.java","lineNumber":183,"sourceCode":"    public List<String> getFileNamesByPath(String path) throws IOException {\n        List<FileStatus> candidates = new ArrayList<>();\n        FileDiscoveryScanner.ScanStats scanStats;\n        try (FileStatusListingSession session =\n                hadoopFileSystemProxy.openFileStatusListingSession()) {\n            scanStats =\n                    FileDiscoveryScanner.scan(\n                            new Path(path),\n                            recursiveFileScan,\n                            session,\n                            this::isSourceCandidate,\n                            candidates::add);\n        } catch (IOException e) {\n            Path sourcePath = new Path(path);\n            String protocol =\n                    sourcePath.toUri().getScheme() == null\n                            ? hadoopFileSystemProxy.getScheme()\n                            : sourcePath.toUri().getScheme();\n            throw new IOException(\n                    \"Failed during source_listing setup/scan for protocol=\"\n                            + protocol\n                            + \", path=\"\n                            + maskUriUserInfo(path),\n                    e);\n        }\n\n        List<FileInfo> fileInfoList = new ArrayList<>(candidates.size());\n        UpdateFileMetadataLoader.Result updateResult = null;\n        long skipped = 0;\n        if (enableUpdateSync) {\n            if (targetHadoopFileSystemProxy == null) {\n                initTargetHadoopFileSystemProxy();\n            }\n            List<UpdateFileMetadataLoader.Request> requests = new ArrayList<>(candidates.size());\n            for (int i = 0; i < candidates.size(); i++) {\n                String sourceFilePath = candidates.get(i).getPath().toString();\n                String relativePath = resolveRelativePath(sourceRootPath, sourceFilePath);","sourceCodeStart":165,"sourceCodeEnd":201,"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/AbstractReadStrategy.java#L165-L201","documentation":"AbstractReadStrategy.getFileNamesByPath wraps any IOException from listing/setting up the Hadoop filesystem scan into an IOException naming the URI scheme and the (userinfo-masked) path. It indicates the file discovery phase itself failed — network, permissions, missing filesystem implementation, or bad URI — not a problem with individual files' content.","triggerScenarios":"An IOException is raised while creating the Hadoop Path/FileSystem or listing statuses in getFileNamesByPath (e.g. unknown scheme, connection failure to HDFS/S3, permission denied); the strategy rethrows with protocol= and path= context (AbstractReadStrategy.java:183).","commonSituations":"Missing s3a/oss filesystem jars on the classpath (UnknownHostException/NoClassDefFoundError chain); HDFS NameNode unreachable; IAM/kerberos credentials missing; path URI malformed.","solutions":["Check the protocol in the message and confirm the matching Hadoop filesystem dependency/config is present.","Test connectivity and credentials: `hdfs dfs -ls` or an s3 client list with the same settings as the job.","Verify the path URI is well-formed and the scheme matches an available filesystem.","Inspect the wrapped cause (the `e` chained in the IOException) for the exact storage-level error."],"exampleFix":"// before\npath = \"s3a://bucket/data\"  // no s3a filesystem jars on classpath\n// after\n# add seatunnel-hadoop3-3.1.4-uber jar / hadoop-aws to plugin dir, then\npath = \"s3a://bucket/data\"","handlingStrategy":"try-catch","validationCode":"// Pre-flight listing with the same Hadoop conf the job uses\nPath p = new Path(path);\nFileSystem fs = p.getFileSystem(conf);\nfs.listStatus(p); // throws early with a clearer stack","typeGuard":null,"tryCatchPattern":"try {\n    // source read\n} catch (IOException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Failed during source_listing setup/scan\")) {\n        log.error(\"File discovery failed; check protocol jars, connectivity and permissions for path\", e.getCause());\n    }\n    throw e;\n}","preventionTips":["Ship the correct Hadoop filesystem uber jars (hdfs/s3a/oss) in the plugin dir.","Pre-flight list the path with the same credentials before job launch.","Mask-free test: resolve scheme explicitly in the URI."],"tags":["io","hadoop","file-discovery"],"backgroundTag":"file-not-found","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}