{"record":{"id":"946b2235ff60115b","repo":"quarkusio/quarkus","slug":"cannot-serve-directory","errorCode":null,"errorMessage":"Cannot serve directory","messagePattern":"Cannot serve directory","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"extensions/undertow/runtime/src/main/java/io/quarkus/undertow/runtime/KnownPathResourceManager.java","lineNumber":173,"sourceCode":"                            }\n                        }\n                    } else {\n                        break;\n                    }\n                }\n            }\n\n            return ret;\n        }\n\n        @Override\n        public String getContentType(MimeMappings mimeMappings) {\n            return null;\n        }\n\n        @Override\n        public void serveBlocking(OutputStream outputStream, HttpServerExchange exchange) throws IOException {\n            throw new IOException(\"Cannot serve directory\");\n        }\n\n        @Override\n        public void serveAsync(OutputChannel stream, HttpServerExchange exchange) {\n            exchange.setStatusCode(500);\n            exchange.endExchange();\n        }\n\n        @Override\n        public Long getContentLength() {\n            return null;\n        }\n\n        @Override\n        public String getCacheKey() {\n            return null;\n        }\n","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/undertow/runtime/src/main/java/io/quarkus/undertow/runtime/KnownPathResourceManager.java#L155-L191","documentation":"KnownPathResourceManager's DirectoryResource cannot write directory contents to an HTTP response, so serveBlocking throws IOException(\"Cannot serve directory\") (serveAsync returns 500). Undertow's static resource handler hit a request whose resolved resource is a directory rather than a file.","triggerScenarios":"An HTTP request maps exactly to a known directory path (e.g. /static/ or /images) and no welcome-file/index handling redirects it to a file.","commonSituations":"Requesting a directory URL directly with KnownPathResourceManager; misconfigured route sending / to static resources without an index.html present.","solutions":["Add an index.html to the directory or route directory requests to a specific file","Use quarkus.http.enable-directories or a rewrite/redirect so directory paths are not served as resources","Change the route so directory URLs are handled by your own handler instead of the static resource manager"],"exampleFix":"// before: request GET / -> static resource manager, no index.html\n// after: add index.html in META-INF/resources/ or configure redirect\nquarkus.http.enable-directories=true // or handle / with a route returning index.html","handlingStrategy":"fallback","validationCode":"// guard in a custom route handler\nFile file = Paths.get(baseDir, path).toFile();\nif (file.isDirectory()) {\n    resp.sendRedirect(path + \"/index.html\");\n    return;\n}","typeGuard":null,"tryCatchPattern":"try {\n    resourceManager.serveBlocking(out, exchange);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"Cannot serve directory\")) {\n        exchange.setStatusCode(404).endExchange();\n    }\n}","preventionTips":["Always ship an index.html for served directories","Redirect bare directory URLs in routing config","Test requests to directory paths"],"tags":["quarkus","static-resources","undertow","directory"],"backgroundTag":"directory-request-unhandled","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"}