{"record":{"id":"2b60cfc8aed3eac7","repo":"quarkusio/quarkus","slug":"file-is-not-a-regular-file-file-2b60cf","errorCode":null,"errorMessage":"File is not a regular file: ${file}","messagePattern":"File is not a regular file: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/PathPart.java","lineNumber":39,"sourceCode":"    public final long offset;\n\n    /**\n     * The number of bytes to send\n     */\n    public final long count;\n\n    /**\n     * Create a new partial {@link Path} object.\n     *\n     * @param file The file to send\n     * @param offset The starting byte of the file (must be >= 0)\n     * @param count The number of bytes to send (must be >= 0 and offset+count <= file size)\n     */\n    public PathPart(Path file, long offset, long count) {\n        if (!Files.exists(file))\n            throw new IllegalArgumentException(\"File does not exist: \" + file);\n        if (!Files.isRegularFile(file))\n            throw new IllegalArgumentException(\"File is not a regular file: \" + file);\n        if (!Files.isReadable(file))\n            throw new IllegalArgumentException(\"File cannot be read: \" + file);\n        if (offset < 0)\n            throw new IllegalArgumentException(\"Offset (\" + offset + \") must be >= 0: \" + file);\n        if (count < 0)\n            throw new IllegalArgumentException(\"Count (\" + count + \") must be >= 0: \" + file);\n        long fileLength;\n        try {\n            fileLength = Files.size(file);\n            if ((offset + count) > fileLength)\n                throw new IllegalArgumentException(\n                        \"Offset + count (\" + (offset + count) + \") larger than file size (\" + fileLength + \"): \" + file);\n        } catch (IOException e) {\n            throw new UncheckedIOException(e);\n        }\n        this.file = file;\n        this.offset = offset;\n        this.count = count;","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/PathPart.java#L21-L57","documentation":"PathPart wraps a regular file for range-based response streaming. It throws this IllegalArgumentException when the Path exists but is not a regular file (e.g. a directory or special file), because only regular files support byte-range reads of a known size.","triggerScenarios":"Calling `new PathPart(file, offset, count)` with a Path that points to a directory, a device/special file, or (on some platforms) a named pipe — `Files.isRegularFile(file)` returns false.","commonSituations":"Serving a directory listing path passed directly to the file API; path-traversal requests that resolve to a directory or /dev/ entry; symlink targets pointing at sockets/pipes; OpenAPI/docs examples that treat an upload directory as a downloadable file.","solutions":["Check `Files.isDirectory(file)` in the caller and return 404 or redirect instead of constructing PathPart.","Point PathPart at the concrete file, not a directory; append the filename when the user requests a folder path.","Normalize/validate user-supplied paths (reject directory or symlink targets) before constructing the part."],"exampleFix":"// before\nPath requested = Path.of(baseDir, userPath);\nPathPart part = new PathPart(requested, 0, Files.size(requested));\n// after\nPath requested = Path.of(baseDir, userPath).normalize();\nif (!requested.startsWith(baseDir) || !Files.isRegularFile(requested)) {\n    return Response.status(Response.Status.NOT_FOUND).build();\n}\nPathPart part = new PathPart(requested, 0, Files.size(requested));","handlingStrategy":"validation","validationCode":"if (file == null || !Files.isRegularFile(file)) {\n    return Response.status(Response.Status.NOT_FOUND).build();\n}","typeGuard":"boolean isRegularFile(Path p) {\n    return p != null && Files.isRegularFile(p);\n}","tryCatchPattern":"try {\n    return Response.ok(new PathPart(file, offset, count)).build();\n} catch (IllegalArgumentException e) {\n    return Response.status(Response.Status.NOT_FOUND).build();\n}","preventionTips":["Reject directory and symlink-to-directory requests explicitly with 404.","Normalize user paths and confine them to a base directory to avoid traversal into special files.","Treat any user-supplied path as untrusted: check isRegularFile before serving."],"tags":["filesystem","illegal-argument","resteasy-reactive","path-traversal"],"backgroundTag":"not-a-regular-file","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}