quarkusio/quarkus · error · IllegalArgumentException

Unable to validate specified Dockerfile: '%s'

Error message

Unable to validate specified Dockerfile: '%s'

What it means

If reading the Dockerfile lines throws an IOException during the FROM-directive scan, validate() throws IllegalArgumentException("Unable to validate specified Dockerfile: '<path>'"). Note the IOException cause is dropped (not chained), so only the path is reported — the underlying issue is an I/O error while opening/reading the file (permissions, I/O failure, race with deletion).

Source

Thrown at extensions/container-image/container-image-openshift/deployment/src/main/java/io/quarkus/container/image/openshift/deployment/ApplyDockerfileToBuildConfigDecorator.java:48

        if (!file.exists()) {
            throw new IllegalArgumentException(
                    "Specified Dockerfile: '" + pathToDockerfile.toAbsolutePath().toString() + "' does not exist.");
        }
        if (!file.isFile()) {
            throw new IllegalArgumentException(
                    "Specified Dockerfile: '" + pathToDockerfile.toAbsolutePath().toString() + "' is not a normal file.");
        }

        try {
            Stream<String> lines = Files.lines(pathToDockerfile);
            Optional<String> fromLine = lines.filter(l -> !l.startsWith("#")).map(String::trim)
                    .filter(l -> l.startsWith("FROM")).findFirst();
            if (!fromLine.isPresent()) {
                throw new IllegalArgumentException("Specified Dockerfile: '" + pathToDockerfile.toAbsolutePath().toString()
                        + "' does not contain a FROM directive");
            }
        } catch (IOException e) {
            throw new IllegalArgumentException(
                    "Unable to validate specified Dockerfile: '" + pathToDockerfile.toAbsolutePath().toString() + "'");
        }
    }

    @Override
    public void andThenVisit(final BuildConfigSpecFluent<?> spec, ObjectMeta meta) {
        try (InputStream is = new FileInputStream(pathToDockerfile.toFile())) {
            spec.withNewSource()
                    .withDockerfile(new String(FileUtil.readFileContents(is)))
                    .endSource()
                    .withNewStrategy()
                    .withNewDockerStrategy()
                    .endDockerStrategy()
                    .endStrategy();
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Check read permissions on the Dockerfile for the user running the build (chmod a+r)
2. Re-run the build to rule out a transient race with a concurrent clean/delete
3. Inspect filesystem health (dmesg / mount) if on NFS or CI volumes; check SELinux denials (ausearch -m avc)
4. As a diagnostic, cat the exact absolute path printed in the message

Example fix

# before: unreadable Dockerfile in CI
-rw------- 1 root root Dockerfile
// after: make it readable for the build user
# chmod 644 src/main/docker/Dockerfile

// ensure the Dockerfile is readable before the build
java.nio.file.Path df = java.nio.file.Path.of(dockerfileConfig);
if (!java.nio.file.Files.isReadable(df)) {
    throw new IllegalStateException("Dockerfile not readable: " + df.toAbsolutePath());
}

try {
    openshiftBuild();
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unable to validate specified Dockerfile")) {
        // cause is swallowed by the library — check permissions/FS manually
        throw new IllegalStateException("I/O error reading " + dockerfileConfig + ": check permissions, SELinux, NFS", e);
    }
    throw e;
}

When it happens

Trigger: Files.lines(pathToDockerfile) fails: unreadable permissions, file deleted between the exists() check and the read, I/O errors on network filesystems, or the path being a unreadable special file that passed the earlier checks.

Common situations: Running the build as a user without read permission on the Dockerfile, NFS/CI volume flakiness, file removed concurrently by a clean step, SELinux denying read access in containerized CI.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to restore the timestamp of the file:
• Specified Dockerfile: '%s' does not exist.
• Specified Dockerfile: '%s' is not a normal file.
• Specified Dockerfile: '%s' does not contain a FROM directive
• Build report file cannot be written to:

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