What causes "Service Binding root '" + p + "' is not a directory" in quarkusio/quarkus?

Ensure SERVICE_BINDING_ROOT points to a directory containing one subdirectory per binding.

quarkusio/quarkus · error · IllegalArgumentException

Service Binding root '" + p + "' is not a directory

Error message

Service Binding root '" + p + "' is not a directory

What it means

KubernetesServiceBindingConfigSourceFactory.getServiceBindings validates that the Service Binding root path (typically /k8s/service-binding or a path in bindings config) is a directory and throws IllegalArgumentException if the path exists but is not a directory. This is a configuration/paths validation guard: a file was placed where a directory of service binding directories is expected.

Source

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

            Map<String, String> rawConfigSourceProperties = new HashMap<>();
            for (Map.Entry<String, String> entry : serviceBindingProperties.entrySet()) {
                rawConfigSourceProperties.put("quarkus.service-binding." + serviceBinding.getName() + "." + entry.getKey(),
                        entry.getValue());
            }
            result.add(new ServiceBindingConfigSource("service-binding-" + serviceBinding.getName() + "-raw",
                    rawConfigSourceProperties));
        }
        return result;
    }

    static List<ServiceBinding> getServiceBindings(String bindingRoot) {
        Path p = Paths.get(bindingRoot);
        if (!Files.exists(p)) {
            log.warn("Service Binding root '" + p.toAbsolutePath() + "' does not exist");
            return emptyList();
        }
        if (!Files.isDirectory(p)) {
            throw new IllegalArgumentException("Service Binding root '" + p + "' is not a directory");
        }

        File[] files = p.toFile().listFiles();
        if (files == null) {
            log.warn("Service Binding root '" + p.toAbsolutePath() + "' does not contain any sub-directories");
            return emptyList();
        } else {
            log.debug("Found " + files.length + " potential Service Binding directories");
            List<ServiceBinding> serviceBindings = new ArrayList<>(files.length);
            for (File f : files) {
                ServiceBinding sb = new ServiceBinding(f.toPath());
                serviceBindings.add(sb);
                if (log.isDebugEnabled()) {
                    log.debug(String.format("Directory '%s' contains %d %s and will be used as Service Binding %s",
                            f.toPath().toAbsolutePath(), sb.getProperties().size(),
                            sb.getProperties().size() == 1 ? "property" : "properties", sb));
                }
            }

View on GitHub (pinned to e1c734241f)

Solutions

Ensure SERVICE_BINDING_ROOT points to a directory containing one subdirectory per binding.
Fix the volume mount so a directory (not a file) is mounted at the binding root.
Correct the path value if SERVICE_BINDING_ROOT was set by hand in your environment.
If the path doesn't exist at all the factory just warns — check the warning: a wrong path that resolves to a file means a stale or wrong mount.

Example fix

// before (env): SERVICE_BINDING_ROOT=/etc/bindings/bindings.json
// after: point to a directory of binding dirs
export SERVICE_BINDING_ROOT=/etc/bindings
mkdir -p /etc/bindings/my-db
echo postgres > /etc/bindings/my-db/type

Defensive patterns

Strategy: validation

Validate before calling

Path root = Paths.get(System.getenv().getOrDefault("SERVICE_BINDING_ROOT", "/k8s/service-binding"));
if (Files.exists(root) && !Files.isDirectory(root)) {
    throw new IllegalStateException("SERVICE_BINDING_ROOT must be a directory: " + root);
}

Type guard

static boolean isValidBindingRoot(String p) {
    Path root = Paths.get(p);
    return Files.exists(root) && Files.isDirectory(root);
}

Try / catch

try {
    loadServiceBindings();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is not a directory")) {
        log.warn("Fix SERVICE_BINDING_ROOT: {}", e.getMessage());
    }
}

Prevention

Mount a directory (volume), never a single file, at the binding root path.
Echo $SERVICE_BINDING_ROOT in startup logs to catch misconfiguration early.
In tests, create the binding tree with Files.createTempDirectory.
Validate the mount shape in CI with a pre-start script: [ -d "$SERVICE_BINDING_ROOT" ].

When it happens

Trigger: SERVICE_BINDING_ROOT (or quarkus.kubernetes-service-binding.root) points at an existing regular file or symlink-to-file instead of a directory containing per-binding subdirectories.

Common situations: Mount mistake in Kubernetes (mounting a file over the binding root path); misconfigured SERVICE_BINDING_ROOT env var in dev/test; testing with a stub file instead of a directory tree.

Related errors

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