oracle/graal · error · IOException

Unknown replay singleton kind

Error message

Unknown replay singleton kind 

What it means

readSpecialSingleton maps a small int kind to well-known singleton constants (JavaConstant.NULL_POINTER, HotSpotCompressedNullConstant.COMPRESSED_NULL, SpeculationLog.NO_SPECULATION, ValueKind.Illegal). Any other kind value throws IOException 'Unknown replay singleton kind <kind>'. The kind byte is only ever written from this fixed set, so an unknown kind indicates corruption or reader/writer format divergence.

Source

Thrown at compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/hotspot/replaycomp/BinaryReplayCodec.java:1094

            default -> throw new IOException("Invalid replay boolean flag " + value);
        };
    }

    private int registrationIndex(CompilerInterfaceDeclarations.Registration registration) {
        Integer index = registrationIndices.get(registration.clazz());
        if (index == null) {
            throw new IllegalArgumentException("Unknown registration " + registration.clazz().getName());
        }
        return index;
    }

    private static Object readSpecialSingleton(int kind) throws IOException {
        return switch (kind) {
            case SINGLETON_NULL_POINTER -> JavaConstant.NULL_POINTER;
            case SINGLETON_COMPRESSED_NULL -> HotSpotCompressedNullConstant.COMPRESSED_NULL;
            case SINGLETON_NO_SPECULATION -> SpeculationLog.NO_SPECULATION;
            case SINGLETON_ILLEGAL_VALUE_KIND -> ValueKind.Illegal;
            default -> throw new IOException("Unknown replay singleton kind " + kind);
        };
    }

    private Class<?> arrayComponentType(Object[] array) {
        Class<?> componentType = array.getClass().getComponentType();
        Class<?> registeredSupertype = declarations.findRegisteredSupertype(componentType);
        return (registeredSupertype != null) ? registeredSupertype : componentType;
    }

    private static String requireNonNullString(String value, String description) throws IOException {
        if (value == null) {
            throw new IOException("Required replay field " + description + " is null");
        }
        return value;
    }

    private static Register findRegister(Architecture architecture, int number) throws IOException {
        for (Register register : architecture.getRegisters()) {

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Regenerate the replay file on the same GraalVM build used for replay
2. If extending the singleton set in a fork, add the kind symmetrically and bump VERSION
3. Validate the version header first to fail fast

try {
    result = codec.readReplay(in);
} catch (IOException e) {
    if ("Unknown replay singleton kind".equals(e.getMessage())) {
        // reader/writer singleton set mismatch: re-record
    } else throw e;
}

When it happens

Trigger: Replaying a stream written by a build with additional singleton kinds; stream misalignment after an earlier parse discrepancy; corrupted file.

Common situations: Cross-version replay after the singleton set was extended without bumping the file VERSION; partially-written replay files.

Related errors

• Unknown enum constant for
• Unknown replay marker kind
• Unknown replay assumption kind
• Unknown replay tag
• Unknown replay architecture kind

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