quarkusio/quarkus · error · RuntimeException

Failed to open DirectoryStream for configured certificate pa

Error message

Failed to open DirectoryStream for configured certificate path + certificateDirectory

What it means

streamDirectory calls Files.newDirectoryStream to open the certificate directory; an IOException while opening is wrapped in a RuntimeException 'Failed to open DirectoryStream for configured certificate path <path>'. This means the path exists and is a directory, but the JVM could not open it for listing.

Source

Thrown at extensions/tls-registry/runtime/src/main/java/io/quarkus/tls/runtime/config/PemCertsConfig.java:106

        return options;
    }

    private static DirectoryStream<Path> streamDirectory(Path certificateDirectory) {
        if (Files.notExists(certificateDirectory)) {
            throw new ConfigurationException("Configured certificate path does not exist:" + certificateDirectory);
        }

        if (!Files.isDirectory(certificateDirectory)) {
            throw new ConfigurationException("Path '" + certificateDirectory + "' is not a directory. Paths pointing "
                    + "to the certificate files can be configured with the 'quarkus.tls.trust-store.pem.certs' property"
                    + " instead");
        }

        try {
            return Files.newDirectoryStream(certificateDirectory);
        } catch (IOException e) {
            throw new RuntimeException("Failed to open DirectoryStream for configured certificate path " + certificateDirectory,
                    e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Check the chained IOException cause (usually FileSystemException with reason)
Fix filesystem permissions so the process user can read/list the directory
Verify the directory still exists at startup and no cleanup job removes it concurrently
Check container security policies (SELinux/AppArmor) that could block the path

Example fix

# before (permission denied)
# after, in Dockerfile
COPY --chown=185:185 certs /deployments/certs
RUN chmod -R u+rX /deployments/certs

Defensive patterns

Strategy: validation

Validate before calling

for (Path dir : certDirs) {
    if (!Files.isDirectory(dir)) throw new IllegalStateException("Not a directory: " + dir);
    if (!Files.isReadable(dir)) throw new IllegalStateException("Not readable: " + dir);
    try (var s = Files.list(dir)) { s.findAny(); } // probe open
}

Type guard

static boolean canOpenDirectoryStream(Path dir) {
    if (!Files.isDirectory(dir)) return false;
    try (var s = Files.newDirectoryStream(dir)) { return true; }
    catch (IOException e) { return false; }
}

Try / catch

try {
    options = pemCertsConfig.toOptions();
} catch (RuntimeException e) {
    if (e.getCause() instanceof java.nio.file.AccessDeniedException ade)
        log.error("Permission denied opening cert dir: " + ade.getFile());
    throw e;
}

Prevention

Grant the runtime user read+execute on cert directories
Check SELinux/AppArmor labels on mounted cert paths
Avoid racing directory cleanup with application startup
Test startup as the same user the container runs as

When it happens

Trigger: Files.newDirectoryStream throwing IOException on a certDir configured via quarkus.tls.<name>.pem.certDirs — permission denied, I/O error, or the path was removed between the isDirectory check and the open (race).

Common situations: Running as a non-root container user without read permission on the mounted certs directory; disk I/O errors; directory deleted by a concurrent process; SELinux/AppArmor denial on the path.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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