quarkusio/quarkus · critical · IOException

Invalid magic number in AOT cache file: expected 0x${MAGIC}

Error message

Invalid magic number in AOT cache file: expected 0x${MAGIC} but got 0x${magic}

What it means

AotSerializedApplication.read() validates the quarkus-application.dat cache file by reading a 4-byte magic number that must equal MAGIC. A mismatch means the file is not a valid Quarkus AOT cache — it is a different file, truncated, corrupted, or written by an incompatible build — and an IOException is thrown describing both the expected and actual magic values.

Source

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

                    data.write(configEntry.content());
                }
            }
            data.flush();
        }
    }

    /**
     * Reads cached resources from an input stream.
     *
     * @param in the input stream to read from
     * @return an AotSerializedApplication containing the main class and cached resources
     * @throws IOException if an I/O error occurs or the format is invalid
     */
    public static AotSerializedApplication read(InputStream in) throws IOException {
        try (DataInputStream data = new DataInputStream(in)) {
            int magic = data.readInt();
            if (magic != MAGIC) {
                throw new IOException("Invalid magic number in AOT cache file: expected 0x"
                        + Integer.toHexString(MAGIC) + " but got 0x" + Integer.toHexString(magic));
            }

            int version = data.readInt();
            if (version != VERSION) {
                throw new IOException("Unsupported AOT cache version: expected " + VERSION + " but got " + version);
            }

            String mainClass = data.readUTF();

            // Read tracked directories
            int fullyIndexedDirectoryCount = data.readInt();
            Set<String> fullyIndexedDirectories = new HashSet<>((int) Math.ceil(fullyIndexedDirectoryCount / 0.75f));
            for (int i = 0; i < fullyIndexedDirectoryCount; i++) {
                fullyIndexedDirectories.add(data.readUTF());
            }

            // Read directory contents

View on GitHub (pinned to e1c734241f)

Solutions

Rebuild the application with the aot-jar packaging type to regenerate a correct quarkus-application.dat.
Delete the stale/corrupted cache file and re-deploy the full target/quarkus-app directory.
Verify the file being read is actually quarkus-application.dat and not another artifact at the same path.

Example fix

// before
app = AotSerializedApplication.read(Files.newInputStream(stalePath));

// after: regenerate then read
// mvn clean package -Dpackaging.type=aot-jar
app = AotSerializedApplication.read(Files.newInputStream(appRoot.resolve("quarkus-application.dat")));

Defensive patterns

Strategy: validation

Validate before calling

Path cache = Paths.get("target/quarkus-app/quarkus-application.dat");
try (DataInputStream in = new DataInputStream(new BufferedInputStream(Files.newInputStream(cache)))) {
    int magic = in.readInt();
    if (magic != 0x51554152 /* expected MAGIC */) throw new IllegalStateException("Not a Quarkus AOT cache file");
}

Try / catch

try {
    app = AotSerializedApplication.read(in);
} catch (IOException e) {
    if (e.getMessage().startsWith("Invalid magic number")) {
        throw new IllegalStateException("Corrupt/wrong cache file; rebuild with mvn clean package", e);
    } throw e;
}

Prevention

Never hand-edit or replace quarkus-application.dat.
Verify checksums when copying artifacts between environments.
Rebuild cleanly when switching build types.

When it happens

Trigger: Passing an InputStream of a file that is not a Quarkus AOT cache (wrong file at the QUARKUS_APPLICATION_DAT path, partially written/corrupted file, or text/HTML content such as an error page saved where the cache should be).

Common situations: Truncated uploads or container layer caches serving a stale/partial quarkus-application.dat, manually replaced cache files, or reading the file from the wrong directory.

Related errors

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