quarkusio/quarkus · critical · IllegalStateException

Serialized application file not found or not readable: ${cac

Error message

Serialized application file not found or not readable: ${cacheFile}. The application may not have been packaged correctly with aot-jar type.

What it means

After locating the app root, AotQuarkusEntryPoint.doRun() loads the serialized application image from QUARKUS_APPLICATION_DAT (quarkus-application.dat). If that file does not exist or is not readable, the packaged application is incomplete — the AOT cache was never written or was excluded — so startup aborts with this IllegalStateException.

Source

Thrown at independent-projects/bootstrap/runner/src/main/java/io/quarkus/bootstrap/runner/AotQuarkusEntryPoint.java:57

        }
    }

    private static void doRun(String... args) throws Throwable {
        Path jarPath = QuarkusEntryPoint.resolveJarPath(AotQuarkusEntryPoint.class);
        if (jarPath == null) {
            throw new IllegalStateException("Unable to determine launch jar path");
        }
        Path appRoot = jarPath.getParent().getParent().getParent();

        // Load cached resources and main class name
        AotSerializedApplication app;
        Path cacheFile = appRoot.resolve(QUARKUS_APPLICATION_DAT);
        if (Files.isReadable(cacheFile)) {
            try (InputStream in = new BufferedInputStream(Files.newInputStream(cacheFile), 8192)) {
                app = AotSerializedApplication.read(in);
            }
        } else {
            throw new IllegalStateException("Serialized application file not found or not readable: " + cacheFile
                    + ". The application may not have been packaged correctly with aot-jar type.");
        }

        final AotRunnerClassLoader aotRunnerClassLoader = app.getRunnerClassLoader();
        try {
            Thread.currentThread().setContextClassLoader(aotRunnerClassLoader);
            QuarkusForkJoinWorkerThread.setQuarkusAppClassloader(aotRunnerClassLoader);
            Class<?> mainClass = aotRunnerClassLoader.loadClass(app.getMainClass());
            MethodHandles.Lookup lookup = MethodHandles.lookup();
            lookup.findStatic(mainClass, "main", MethodType.methodType(void.class, String[].class)).invokeExact(args);
        } finally {
            QuarkusForkJoinWorkerThread.setQuarkusAppClassloader(null);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Rebuild the application with the aot-jar packaging type (mvn clean package) so quarkus-application.dat is generated.
Copy/deploy the full target/quarkus-app directory, including quarkus-application.dat.
Verify the artifact being launched actually corresponds to the aot-jar build, not a fast-jar build.

Example fix

// before (partial copy)
cp target/quarkus-app/quarkus-run.jar /app/

// after
cp -r target/quarkus-app/ /app/

Defensive patterns

Strategy: validation

Validate before calling

Path cache = Paths.get("target/quarkus-app/quarkus-application.dat");
if (!Files.isReadable(cache)) {
    throw new IllegalStateException("quarkus-application.dat missing; rebuild with aot-jar packaging");
}

Try / catch

try {
    AotQuarkusEntryPoint.main(args);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Serialized application file not found")) {
        System.err.println("Repackage with aot-jar type and deploy the full quarkus-app directory");
    } else throw e;
}

Prevention

Deploy the entire target/quarkus-app directory, never individual files.
Ensure Docker COPY includes quarkus-application.dat.
Rebuild after any packaging-type change.

When it happens

Trigger: Running the AOT entry point when quarkus-application.dat is missing from the appRoot directory, i.e. the jar was not packaged with the aot-jar type or the cache file was deleted/excluded during packaging/deployment.

Common situations: Copying only some files from target/quarkus-app, container images that exclude the .dat file, mixing artifacts from a regular fast-jar build with the AOT entry point, or an outdated/incorrect packaging configuration.

Related errors

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