oracle/graal · error · GraalError

%s: failed compile-time assertion: %s

Error message

%s: failed compile-time assertion: %s

What it means

AssertionNode is the lowering of GraalError.staticAssert / assertion NodeIntrinsic inside snippets: it expects the condition to be constant-folded by codegen time. generate() throws GraalError('<node>: failed compile-time assertion: <message>') when the condition constant-folds to 0 (a genuine failed invariant), and a variant message when the condition is still non-constant.

Source

Thrown at compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/replacements/nodes/AssertionNode.java:115

         * Assertions with a constant "false" value do not immediately cause an error, since they
         * may be unreachable and could thus be removed by later optimizations.
         */
        return this;
    }

    @Override
    public void lower(LoweringTool tool) {
        if (!compileTimeAssertion) {
            tool.getLowerer().lower(this, tool);
        }
    }

    @Override
    public void generate(NodeLIRBuilderTool generator) {
        assert compileTimeAssertion;
        if (condition.isConstant()) {
            if (condition.asJavaConstant().asInt() == 0) {
                throw new GraalError("%s: failed compile-time assertion: %s", this, message);
            }
        } else {
            throw new GraalError("%s: failed compile-time assertion (value %s): %s. Condition must be constant.", this, condition, message);
        }
    }

    @NodeIntrinsic
    public static native void assertion(@ConstantNodeParameter boolean compileTimeAssertion, boolean condition, @ConstantNodeParameter String message, @ConstantNodeParameter Object msgArg1,
                    @ConstantNodeParameter Object msgArg2, long arg1, long arg2);

    public static void staticAssert(boolean condition, String message) {
        assertion(true, condition, message, "", "", 0L, 0L);
    }

    public static void staticAssert(boolean condition, String message, Object msgArg1, Object msgArg2) {
        assertion(true, condition, message, msgArg1, msgArg2, 0L, 0L);
    }

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. If the invariant is genuinely violated, fix the code that establishes it — the error message you passed to staticAssert states what broke.
2. If the condition isn't folding, make the inputs compile-time constants (@ConstantNodeParameter, snippet constants) so the assertion can be evaluated.
3. For checks that should only fire in debug builds, use plain assert instead of staticAssert.

Example fix

// before
GraalError.staticAssert(length >= 0, "length must be non-negative"); // failed for length=-1 input

// fix the producer of the invalid value, and guard non-constant cases at runtime:
if (length < 0) {
    throw new IllegalArgumentException("length must be non-negative");
}

// Hoist the invariant into a plain Java check you can unit-test before it reaches the compiler
static void checkInvariant(int length) {
    if (length < 0) {
        throw new IllegalArgumentException("length must be non-negative, got " + length);
    }
}
// then: checkInvariant(length); GraalError.staticAssert(length >= 0, "length must be non-negative");

When it happens

Trigger: A staticAssert in snippet/intrinsic code whose condition evaluates to false during compilation of a specific input; or whose condition could not be constant-folded at all (inputs not @ConstantNodeParameter / not propagatable).

Common situations: Writing an invariant about compile-time-known values (stamps, constants, parameters) that is actually violated for some compilation; relying on values that the compiler never folds, causing the non-constant variant.

Related errors

• too many arguments
• Too deep inlining, probably caused by recursive inlining.
• Could not find method in %s named %s
• Can't store into VarargsParameter array
• INVOKEDYNAMIC not supported by %s

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