oracle/graal · error · IllegalArgumentException

Unrecognized version

Error message

Unrecognized version 

What it means

GraphProtocol is the wire encoder for graph dumps; its constructor validates that the requested (major, minor) version does not exceed the encoder's own implemented maximum (MAJOR_VERSION.MINOR_VERSION). A version above what this class knows cannot be encoded, so it throws IllegalArgumentException('Unrecognized version M.m'). This protects against writing a dump stream the encoder itself could not have produced.

Source

Thrown at compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/graphio/GraphProtocol.java:94

    private static final int KLASS = 0x00;
    private static final int ENUM_KLASS = 0x01;

    private static final byte[] MAGIC_BYTES = {'B', 'I', 'G', 'V'};

    private static final int MAJOR_VERSION = 8;
    private static final int MINOR_VERSION = 0;

    private final ConstantPool constantPool;
    private final ByteBuffer buffer;
    private final WritableByteChannel channel;
    private final boolean embedded;
    final int versionMajor;
    final int versionMinor;
    private boolean printing;

    GraphProtocol(WritableByteChannel channel, int major, int minor, boolean embedded) throws IOException {
        if (major > MAJOR_VERSION || (major == MAJOR_VERSION && minor > MINOR_VERSION)) {
            throw new IllegalArgumentException("Unrecognized version " + major + "." + minor);
        }
        this.versionMajor = major;
        this.versionMinor = minor;
        this.constantPool = new ConstantPool();
        this.buffer = ByteBuffer.allocateDirect(256 * 1024);
        this.channel = channel;
        this.embedded = embedded;
        if (!embedded) {
            writeVersion();
            flushEmbedded();
        }
    }

    GraphProtocol(GraphProtocol<?, ?, ?, ?, ?, ?, ?, ?, ?, ?> parent) {
        this.versionMajor = parent.versionMajor;
        this.versionMinor = parent.versionMinor;
        this.constantPool = parent.constantPool;
        this.buffer = parent.buffer;

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Align jar versions so the code choosing the protocol version and the GraphProtocol class implementing it come from the same release.
2. Request a version at or below the library's supported maximum (check GraphProtocol's constants in your dependency).
3. When in doubt, omit the version and let the builder default to the encoder's maximum supported version.

Example fix

// before
output = builder.protocolVersion(8, 0).build(); // encoder only knows up to 7.x

// after
output = builder.build(); // auto-select highest mutually supported version

// keep version selection inside one library version; or verify against the encoder's maximum before building
// GraphProtocol's maximum is package-private; practically: let the Builder choose, don't pass hand-picked future versions.

try {
    output = builder.protocolVersion(major, minor).build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unrecognized version")) {
        output = builder.build(); // fall back to the encoder's own maximum
    } else throw e;
}

When it happens

Trigger: Constructing a GraphProtocol/GraphOutput with a major version greater than GraphProtocol's compiled-in MAJOR_VERSION, or an equal major with a higher minor. Typically happens when caller-side version constants come from a newer graphio library than the GraphProtocol class performing the encoding (split jars / mixed classpath).

Common situations: Classpath mixing old and new Graal/graphio jars after a partial upgrade. Forward-porting code that assumes a future protocol version. Passing an arbitrary 'latest' version constant without checking the library's supported maximum.

Related errors

• Cannot downgrade from minimum required version
• Feature unsupported in version
• Dump properties unsupported in format v.
• Trying to write during graph print.
• Expecting

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/370c09089f551b9d. Report an issue: GitHub.