quarkusio/quarkus · error · UncheckedIOException

Unable to read file: ${relativePath}

Error message

Unable to read file: ${relativePath}

What it means

Thrown as an UncheckedIOException while the AOT serializer's file visitor reads a service file (META-INF/services/*) from an exploded application directory via Files.readAllBytes. It indicates an I/O problem (missing file, permissions, race/deletion) while snapshotting service loader descriptors during application serialization.

Source

Thrown at independent-projects/bootstrap/runner/src/main/java/io/quarkus/bootstrap/runner/AotSerializedApplication.java:253

            try (var is = jarFile.getInputStream(fileEntry)) {
                serviceFiles.computeIfAbsent(fileEntry.getName(), k -> new ArrayList<>())
                        .add(is.readAllBytes());
            } catch (IOException e) {
                throw new UncheckedIOException("Unable to read entry: " + fileEntry.getName() + " from jar: " + jarFile, e);
            }
        }

        @Override
        public void visitRegularFile(Path jar, Path file, String relativePath) {
            if (!isServiceFile(relativePath)) {
                return;
            }

            try {
                serviceFiles.computeIfAbsent(relativePath, k -> new ArrayList<>())
                        .add(Files.readAllBytes(file));
            } catch (IOException e) {
                throw new UncheckedIOException("Unable to read file: " + relativePath, e);
            }
        }

        private static boolean isServiceFile(String resourcePath) {
            return resourcePath.startsWith("META-INF/services/") && resourcePath.length() > 18;
        }
    }

    private static class ApplicationConfigFileJarVisitor implements JarVisitor {

        private final Map<String, List<ApplicationConfigEntry>> applicationConfigFiles = new LinkedHashMap<>();

        public Map<String, List<ApplicationConfigEntry>> getApplicationConfigFiles() {
            return applicationConfigFiles;
        }

        @Override
        public void visitJarFileEntry(JarFile jarFile, ZipEntry fileEntry) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the file at the reported relativePath exists and is readable by the user running the app (ls -l).
2. Re-run a clean build (mvn clean package) to remove stale/broken files in the output directory.
3. Exclude broken symlinks or regenerate the service file; check META-INF/services entries are real files.
4. Check for concurrent processes modifying the directory during AOT serialization.

Example fix

// before (failing)
Files.readAllBytes(file);
// after (defensive check in build/packaging script)
if (!Files.isReadable(file) || Files.size(file) < 0) { throw new IllegalStateException("unreadable service file: " + file); }

Path f = dir.resolve(relativePath);
if (!Files.isRegularFile(f) || !Files.isReadable(f)) throw new IllegalStateException("unreadable service file: " + relativePath);

boolean isReadableRegularFile(Path p) { return p != null && Files.isRegularFile(p) && Files.isReadable(p); }

try { /* serialization run */ } catch (UncheckedIOException e) { if (e.getMessage().startsWith("Unable to read file")) { log.error("Service file unreadable: rebuild app", e); throw new IllegalStateException("Fix classpath directory and rebuild", e); } throw e; }

When it happens

Trigger: AotSerializedApplication serialization walks an application directory and a regular file under META-INF/services/ (length > 18) cannot be read: file deleted between listing and reading, unreadable permissions, symlink to nonexistent target, or underlying filesystem error.

Common situations: Running in a container where the classpath directory is being concurrently rebuilt; restrictive file permissions after packaging; broken symlinks in target/ directories; antivirus/indexing tools briefly locking files on Windows.

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 open path tree with root %s
• Failed to read %s
• Failed to read resources from classpath
• Failed to create output directory for generated sources: %s
• Error reading stream.

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