quarkusio/quarkus · error · IllegalStateException

Unable to find root of Dockerfile files. Consider adding 'sr

Error message

Unable to find root of Dockerfile files. Consider adding 'src/main/docker/' to your project root.

What it means

When no custom Dockerfile is configured, Quarkus auto-detects the default Dockerfiles by locating src/main/docker/ relative to the project root derived from the build output directory. If the project root cannot be found or the docker directory is missing, detect() throws this IllegalStateException.

Source

Thrown at extensions/container-image/container-image-docker-common/deployment/src/main/java/io/quarkus/container/image/docker/common/deployment/CommonProcessor.java:391

            return config.dockerfileJvmPath()
                    .map(dockerfileJvmPath -> ProvidedDockerfile.get(Paths.get(dockerfileJvmPath), outputDirectory))
                    .orElseGet(() -> (packageConfig.jar().type() == JarType.LEGACY_JAR)
                            ? DockerfileDetectionResult.detect(DOCKERFILE_LEGACY_JAR, outputDirectory)
                            : DockerfileDetectionResult.detect(DOCKERFILE_JVM, outputDirectory));
        }
    }

    protected interface DockerfilePaths {
        Path dockerfilePath();

        Path dockerExecutionPath();
    }

    protected record DockerfileDetectionResult(Path dockerfilePath, Path dockerExecutionPath) implements DockerfilePaths {
        protected static DockerfilePaths detect(String resource, Path outputDirectory) {
            var dockerfileToExecutionRoot = findDockerfileRoot(outputDirectory);
            if (dockerfileToExecutionRoot == null) {
                throw new IllegalStateException(
                        "Unable to find root of Dockerfile files. Consider adding 'src/main/docker/' to your project root.");
            }

            var dockerFilePath = dockerfileToExecutionRoot.getKey().resolve(resource);
            if (!Files.exists(dockerFilePath)) {
                throw new IllegalStateException(
                        "Unable to find Dockerfile %s in %s"
                                .formatted(resource, dockerfileToExecutionRoot.getKey().toAbsolutePath()));
            }

            return new DockerfileDetectionResult(dockerFilePath, dockerfileToExecutionRoot.getValue());
        }

        private static Map.Entry<Path, Path> findDockerfileRoot(Path outputDirectory) {
            var mainSourcesRoot = findMainSourcesRoot(outputDirectory);
            if (mainSourcesRoot == null) {
                return null;
            }

View on GitHub (pinned to e1c734241f)

Solutions

Restore the default Dockerfiles (copy from a freshly generated Quarkus project's src/main/docker/)
Or explicitly set quarkus.container-image.docker.dockerfile-jvm-path (and -native-path) to an existing Dockerfile
Ensure the build runs with the standard Maven/Gradle layout so the project root is detected from the output directory
Create src/main/docker/ in the project root if you intentionally manage Dockerfiles there

Example fix

# before: directory removed
# after
mkdir -p src/main/docker && cp <fresh-project>/src/main/docker/Dockerfile.jvm src/main/docker/

Defensive patterns

Strategy: validation

Validate before calling

Path dockerDir = Path.of("src/main/docker");
if (!Files.isDirectory(dockerDir)) {
    throw new IllegalStateException("src/main/docker missing; restore default Dockerfiles or set quarkus.container-image.docker.dockerfile-jvm-path");
}

Type guard

boolean defaultDockerfilesPresent(Path projectRoot) {
    return Files.isDirectory(projectRoot.resolve("src/main/docker"))
        && Files.isRegularFile(projectRoot.resolve("src/main/docker/Dockerfile.jvm"));
}

Try / catch

try {
    buildImage();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("root of Dockerfile")) {
        // restore src/main/docker or configure dockerfile-jvm-path
    } else throw e;
}

Prevention

Keep the generated src/main/docker directory under version control
Configure explicit dockerfile-jvm-path/dockerfile-native-path in non-standard layouts
Do not delete 'unused' Dockerfiles when switching packaging types
Run image builds from the standard project structure

When it happens

Trigger: Building a container image without quarkus.container-image.docker.dockerfile-jvm-path (or -native-path) set while the project lacks a src/main/docker/ directory, or the build runs from an unusual output layout where the sources root cannot be derived from target/ or build/.

Common situations: Deleting the generated src/main/docker directory; building with Gradle from a restructured layout; running the build in a packaged/copied tree that no longer contains src/main/docker; project root detection failing when output dir is moved elsewhere.

Related errors

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