{"record":{"id":"c73bf3e8c63251ca","repo":"oracle/graal","slug":"s-failed-compile-time-assertion-s","errorCode":null,"errorMessage":"%s: failed compile-time assertion: %s","messagePattern":"(.+?): failed compile-time assertion: (.+?)","errorType":"exception","errorClass":"GraalError","httpStatus":null,"severity":"error","filePath":"compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/replacements/nodes/AssertionNode.java","lineNumber":115,"sourceCode":"         * Assertions with a constant \"false\" value do not immediately cause an error, since they\n         * may be unreachable and could thus be removed by later optimizations.\n         */\n        return this;\n    }\n\n    @Override\n    public void lower(LoweringTool tool) {\n        if (!compileTimeAssertion) {\n            tool.getLowerer().lower(this, tool);\n        }\n    }\n\n    @Override\n    public void generate(NodeLIRBuilderTool generator) {\n        assert compileTimeAssertion;\n        if (condition.isConstant()) {\n            if (condition.asJavaConstant().asInt() == 0) {\n                throw new GraalError(\"%s: failed compile-time assertion: %s\", this, message);\n            }\n        } else {\n            throw new GraalError(\"%s: failed compile-time assertion (value %s): %s. Condition must be constant.\", this, condition, message);\n        }\n    }\n\n    @NodeIntrinsic\n    public static native void assertion(@ConstantNodeParameter boolean compileTimeAssertion, boolean condition, @ConstantNodeParameter String message, @ConstantNodeParameter Object msgArg1,\n                    @ConstantNodeParameter Object msgArg2, long arg1, long arg2);\n\n    public static void staticAssert(boolean condition, String message) {\n        assertion(true, condition, message, \"\", \"\", 0L, 0L);\n    }\n\n    public static void staticAssert(boolean condition, String message, Object msgArg1, Object msgArg2) {\n        assertion(true, condition, message, msgArg1, msgArg2, 0L, 0L);\n    }\n","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/replacements/nodes/AssertionNode.java#L97-L133","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["If the invariant is genuinely violated, fix the code that establishes it — the error message you passed to staticAssert states what broke.","If the condition isn't folding, make the inputs compile-time constants (@ConstantNodeParameter, snippet constants) so the assertion can be evaluated.","For checks that should only fire in debug builds, use plain assert instead of staticAssert."],"exampleFix":"// before\nGraalError.staticAssert(length >= 0, \"length must be non-negative\"); // failed for length=-1 input\n\n// fix the producer of the invalid value, and guard non-constant cases at runtime:\nif (length < 0) {\n    throw new IllegalArgumentException(\"length must be non-negative\");\n}","handlingStrategy":"validation","validationCode":"// Hoist the invariant into a plain Java check you can unit-test before it reaches the compiler\nstatic void checkInvariant(int length) {\n    if (length < 0) {\n        throw new IllegalArgumentException(\"length must be non-negative, got \" + length);\n    }\n}\n// then: checkInvariant(length); GraalError.staticAssert(length >= 0, \"length must be non-negative\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Unit-test the invariant's inputs in plain Java before relying on staticAssert during compilation.","Only staticAssert conditions whose inputs are @ConstantNodeParameter or otherwise guaranteed to constant-fold.","For environment-dependent checks, prefer runtime checks (throw in the snippet) over compile-time assertions."],"tags":["graal","assertion","compile-time","snippet","static-assert"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}