quarkusio/quarkus · error · IOException

Cannot serve directory

Error message

Cannot serve directory

What it means

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.

Source

Thrown at extensions/undertow/runtime/src/main/java/io/quarkus/undertow/runtime/KnownPathResourceManager.java:173

                            }
                        }
                    } else {
                        break;
                    }
                }
            }

            return ret;
        }

        @Override
        public String getContentType(MimeMappings mimeMappings) {
            return null;
        }

        @Override
        public void serveBlocking(OutputStream outputStream, HttpServerExchange exchange) throws IOException {
            throw new IOException("Cannot serve directory");
        }

        @Override
        public void serveAsync(OutputChannel stream, HttpServerExchange exchange) {
            exchange.setStatusCode(500);
            exchange.endExchange();
        }

        @Override
        public Long getContentLength() {
            return null;
        }

        @Override
        public String getCacheKey() {
            return null;
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Add an index.html to the directory or route directory requests to a specific file
2. Use quarkus.http.enable-directories or a rewrite/redirect so directory paths are not served as resources
3. Change the route so directory URLs are handled by your own handler instead of the static resource manager

Example fix

// before: request GET / -> static resource manager, no index.html
// after: add index.html in META-INF/resources/ or configure redirect
quarkus.http.enable-directories=true // or handle / with a route returning index.html

// guard in a custom route handler
File file = Paths.get(baseDir, path).toFile();
if (file.isDirectory()) {
    resp.sendRedirect(path + "/index.html");
    return;
}

try {
    resourceManager.serveBlocking(out, exchange);
} catch (IOException e) {
    if (e.getMessage().contains("Cannot serve directory")) {
        exchange.setStatusCode(404).endExchange();
    }
}

When it happens

Trigger: 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.

Common situations: Requesting a directory URL directly with KnownPathResourceManager; misconfigured route sending / to static resources without an index.html present.

Related errors

• Unable to get listed resource ${i} from directory ${path} fo
• Cannot create bean
• io.undertow.server.session.SecureRandomSessionIdGenerator mu
• Invalid configuration: quarkus.http.static-dir.path must poi
• Invalid static resource path '<path>'. Paths must not contai

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/946b2235ff60115b. Report an issue: GitHub.