quarkusio/quarkus · error · IllegalStateException

Unable to determine if file '" + f + "' is a regular file

Error message

Unable to determine if file '" + f + "' is a regular file

What it means

Inside ServiceBinding.accept, while filtering the binding directory's entries, Files.isHidden can throw IOException on a filesystem error; the code wraps it in IllegalStateException('Unable to determine if file X is a regular file'). It signals the directory listing could not be completed reliably — not that the file content is bad.

Source

Thrown at extensions/kubernetes-service-binding/runtime/src/main/java/io/quarkus/kubernetes/service/binding/runtime/ServiceBinding.java:77

        this.name = name;
        this.type = type;
        this.provider = provider;
        this.properties = Collections.unmodifiableMap(properties);
    }

    private static Map<String, String> getFilenameToContentMap(Path directory) {
        if (!Files.exists(directory) || !Files.isDirectory(directory)) {
            log.warn("File '" + directory + "' is not a proper service binding directory so it will skipped");
            return Collections.emptyMap();
        }

        File[] files = directory.toFile().listFiles(new FileFilter() {
            @Override
            public boolean accept(File f) {
                try {
                    return !Files.isHidden(f.toPath()) && !Files.isDirectory(f.toPath());
                } catch (IOException e) {
                    throw new IllegalStateException("Unable to determine if file '" + f + "' is a regular file", e);
                }
            }
        });

        Map<String, String> result = new HashMap<>();
        if (files != null) {
            for (File f : files) {
                try {
                    result.put(f.toPath().getFileName().toString(),
                            Files.readString(f.toPath()).trim());
                } catch (IOException e) {
                    throw new IllegalStateException("Unable to read file '" + f + "'", e);
                }
            }
        }
        return result;
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Check filesystem permissions on the binding root and its files (readable and traversable by the app user).
2. Verify the volume mount is healthy (kubectl describe pod; check mount errors).
3. Retry after the mount settles if the volume was still attaching at startup.
4. Inspect the wrapped IOException cause for the underlying OS error.

Example fix

# before: unreadable binding dir
chmod 000 /k8s/service-binding/my-db
# after
chmod 755 /k8s/service-binding/my-db && chmod 644 /k8s/service-binding/my-db/*

static void checkBindingDirReadable(Path dir) throws IOException {
    if (!Files.isExecutable(dir) || !Files.isDirectory(dir)) {
        throw new IllegalStateException("Binding dir not traversable: " + dir);
    }
    try (var s = Files.list(dir)) {
        s.forEach(f -> {
            if (!Files.isReadable(f)) throw new IllegalStateException("Unreadable: " + f);
        });
    }
}

try {
    loadBindings();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to determine if file")) {
        log.error("Filesystem error scanning binding dir — check mount/permissions", e.getCause());
    }
}

When it happens

Trigger: listFiles on a binding directory encounters a file whose hidden-status check fails — typically permission problems (no execute/search permission on the directory), broken state on network mounts, or an IO error mid-scan of a mounted volume.

Common situations: Service Binding root on a read-only or failing mounted volume; permission churn on the mount; NFS/CIFS filesystem where isHidden raises IOException; files disappearing while scanning.

Related errors

• Unable to read file '" + f + "'
• Failed to create ${classesDir}
• Failed to open DirectoryStream for configured certificate pa
• File cannot be read: ${file}
• Failed to create the project directory: + targetDirectory

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