{"record":{"id":"f95ccb440add0320","repo":"apache/flink","slug":"file-not-found-f95ccb","errorCode":null,"errorMessage":"File not found: {}","messagePattern":"File not found: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"flink-filesystems/flink-s3-fs-native/src/main/java/org/apache/flink/fs/s3native/NativeS3FileSystem.java","lineNumber":281,"sourceCode":"            throw S3ExceptionUtils.toIOException(\n                    String.format(\"Failed to get file status for s3://%s/%s\", bucketName, key), e);\n        }\n    }\n\n    /**\n     * Checks if the given key represents a directory by listing objects with that prefix. Returns a\n     * directory {@link FileStatus} if objects exist under the prefix, otherwise throws {@link\n     * FileNotFoundException}.\n     */\n    private FileStatus getDirectoryStatus(S3Client s3Client, String key, Path path)\n            throws FileNotFoundException {\n        final String prefix = key.endsWith(\"/\") ? key : key + \"/\";\n        final ListObjectsV2Request listRequest =\n                ListObjectsV2Request.builder().bucket(bucketName).prefix(prefix).maxKeys(1).build();\n        final ListObjectsV2Response listResponse = s3Client.listObjectsV2(listRequest);\n\n        if (listResponse.contents().isEmpty() && !listResponse.hasCommonPrefixes()) {\n            throw new FileNotFoundException(\"File not found: \" + path);\n        }\n\n        LOG.debug(\"Path is a directory: {}\", key);\n        return S3FileStatus.withDirectory(path);\n    }\n\n    @Override\n    public BlockLocation[] getFileBlockLocations(FileStatus file, long start, long len) {\n        return new BlockLocation[] {\n            new S3BlockLocation(new String[] {\"localhost\"}, 0, file.getLen())\n        };\n    }\n\n    @Override\n    public FSDataInputStream open(Path path, int bufferSize) throws IOException {\n        checkNotClosed();\n        final String key = NativeS3ObjectOperations.extractKey(path);\n        final S3Client s3Client = clientProvider.getS3Client();","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-filesystems/flink-s3-fs-native/src/main/java/org/apache/flink/fs/s3native/NativeS3FileSystem.java#L263-L299","documentation":"NativeS3FileSystem.getFileStatus, when the key is not an object, calls getDirectoryStatus which lists the bucket with the key as prefix (maxKeys=1). If no objects and no common prefixes exist under that prefix, the path is neither a file nor a non-empty directory, so FileNotFoundException('File not found: <path>') is thrown, matching standard FileSystem contract.","triggerScenarios":"Calling getFileStatus, exists, open, or delete on an S3 path whose key and key-as-prefix both match nothing in the bucket — a typo'd path, an object that was deleted, or a directory that never existed (S3 has no explicit directory markers here).","commonSituations":"Reading from a wrong bucket/path; source objects not yet uploaded when the job starts; paths built with double slashes or missing prefixes; assuming mkdirs creates a visible empty directory (S3 here only recognizes directories that contain objects).","solutions":["Verify the exact key spelling, bucket, and scheme in the path against the S3 console/listing.","Use exists() or catch FileNotFoundException to handle absent paths gracefully instead of failing the job.","If the path is a directory, ensure at least one object exists under its prefix — empty directories are not represented."],"exampleFix":"// before\nFileStatus st = s3Fs.getFileStatus(new Path(\"s3://bucket/typo/path\"));\n\n// after\nPath p = new Path(\"s3://bucket/typo/path\");\nif (!s3Fs.exists(p)) {\n    throw new FileNotFoundException(\"Path does not exist, check bucket/key: \" + p);\n}\nFileStatus st = s3Fs.getFileStatus(p);","handlingStrategy":"try-catch","validationCode":"// cheap pre-check\nif (!s3Fs.exists(path)) {\n    // handle absent path before calling getFileStatus/open\n}","typeGuard":null,"tryCatchPattern":"try {\n    return s3Fs.getFileStatus(path);\n} catch (FileNotFoundException e) {\n    // expected for absent keys on S3: treat as empty/absent input, do not fail the job\n    return null;\n}","preventionTips":["Never assume mkdirs makes an empty directory visible on S3 — directories exist only when objects exist under the prefix.","Validate bucket/key strings (no double slashes, correct scheme) before first use.","Use exists() or catch FileNotFoundException around all optional-path reads."],"tags":["s3","file-not-found","path-handling","object-store-semantics"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}