How to install nodejs runtime on Oracle GraalVM for JDK 21?

[mmilitzer]

Background

We're evaluating using Oracle GraalVM for JDK 21 because it's a LTS version still receiving updates under GFTC until September 2026. Current version is JDK 21.0.5 (GraalVM 23.1.5):

https://www.oracle.com/java/technologies/downloads/?er=221886#graalvmjava21

The documentation of Oracle GraalVM for JDK 21 points to the graaljs github page and advises users to "Navigate to GitHub releases and download Node.js":

https://docs.oracle.com/en/graalvm/jdk/21/docs/reference-manual/js/NodeJS/index.html#running-nodejs-applications

Problem

1. There is no matching nodejs download for the current Oracle GraalVM for JDK 21 (GraalVM 23.1.5) version, the latest 23.x download available is 23.1.2. And we want to run nodejs mainly in JVM mode but the graalnodejs-jvm-23.1.2 tarball is a standalone distribution that bundles the outdated JVM 21.0.2.

2. When I swap out the bundled outdated JVM 21.0.2 against the current 21.0.5 then node does not run anymore and I'm getting compatibility errors:

• node --jvm
  GraalJSAccess.create() failed!
  Exception in thread "main" java.lang.NoClassDefFoundError: Could not initialize class com.oracle.truffle.api.Truffle
  at com.oracle.truffle.enterprise/com.oracle.truffle.runtime.enterprise.EnterpriseTruffle.supportsEnterpriseExtensions(stripped:21)
  at com.oracle.truffle.enterprise/com.oracle.truffle.polyglot.enterprise.EnterprisePolyglotImpl.getPriority(stripped:518)
  at java.base/java.util.Comparator.lambda$comparing$77a9974f$1(Comparator.java:473)
  at java.base/java.util.TimSort.countRunAndMakeAscending(TimSort.java:355)
  at java.base/java.util.TimSort.sort(TimSort.java:220)
  at java.base/java.util.Arrays.sort(Arrays.java:1308)
  at java.base/java.util.ArrayList.sort(ArrayList.java:1804)
  at java.base/java.util.Collections.sort(Collections.java:178)
  at org.graalvm.polyglot/org.graalvm.polyglot.Engine.loadAndValidateProviders(Engine.java:1636)
  at org.graalvm.polyglot/org.graalvm.polyglot.Engine$1.run(Engine.java:1712)
  at org.graalvm.polyglot/org.graalvm.polyglot.Engine$1.run(Engine.java:1707)
  at java.base/java.security.AccessController.doPrivileged(AccessController.java:319)
  at org.graalvm.polyglot/org.graalvm.polyglot.Engine.initEngineImpl(Engine.java:1707)
  at org.graalvm.polyglot/org.graalvm.polyglot.Engine$ImplHolder.(Engine.java:190)
  at org.graalvm.polyglot/org.graalvm.polyglot.Engine.getImpl(Engine.java:442)
  at org.graalvm.polyglot/org.graalvm.polyglot.Engine$Builder.build(Engine.java:740)
  at org.graalvm.polyglot/org.graalvm.polyglot.Context$Builder.build(Context.java:1925)
  at org.graalvm.nodejs/com.oracle.truffle.trufflenode.GraalJSAccess.(GraalJSAccess.java:407)
  at org.graalvm.nodejs/com.oracle.truffle.trufflenode.GraalJSAccess.create(GraalJSAccess.java:456)
  Caused by: java.lang.ExceptionInInitializerError: Exception java.lang.IllegalStateException: Polyglot version compatibility check failed.
  Your Java runtime '21.0.5+9-LTS-jvmci-23.1-b48' with compiler version '23.1.5' is incompatible with polyglot version '23.1.2'.
  Update the org.graalvm.polyglot versions to at least '23.1.5' to resolve this.

3. Your github page mentions that "As of version 23.1.0, GraalJS is available as Maven artifacts" and so I tried upgrading the jars under the ./modules folder to their version 23.1.5 equivalent. However, not all jars seem to be actually available on Maven, e.g. I can't find the "trufflenode.jar". And if I only update the artifacts that are available on Maven (polyglot, js and truffle) then node still doesn't work:

• node --jvm
  GraalJSAccess.create(String[],long) method not found!
  Exception in thread "main" java.lang.NoClassDefFoundError: Could not initialize class com.oracle.truffle.trufflenode.GraalJSAccess
  Caused by: java.lang.ExceptionInInitializerError: Exception java.lang.NullPointerException [in thread "main"]
  at org.graalvm.js/com.oracle.truffle.js.runtime.Symbol.create(Symbol.java:158)
  at org.graalvm.nodejs/com.oracle.truffle.trufflenode.GraalJSAccess.(GraalJSAccess.java:323)

4. When I download the latest graalnodejs-jvm-24.1.1 and swap out the bundled JDK 23 against the JDK 21.0.5 which I actually want to use then "node --jvm" seems to work (at first glance, at least) but it doesn't run in the default --native mode because missing a shared library in the lib folder (which was still included in the 23.1.2 tarball but is not anymore in the latest graalnodejs-jvm-24.1.1 release tarball):

• node --native
  Cannot find ./lib/libgraal-nodejs.so. Specify NODE_JVM_LIB directly.

Question

So, as a user of "Oracle GraalVM for JDK 21" and being on its latest release, how am I supposed to get a nodejs runtime that's compatible and actually works (both in --jvm and --native mode)?

[woess]

Note that Node.js is not part of the official Oracle GraalVM product and not covered by the LTS update policy.
It's released as a standalone distribution; as you've already discovered the right place to download it from is: https://github.com/oracle/graaljs/releases.
There are two standalone distributions, one for the native image version (graalnodejs[-community]-<version>-<platform>) and one based on a GraalVM JDK (graalnodejs[-community]-jvm-<version>-<platform>). You can indeed swap out the bundled JDK with a compatible JDK 21 GraalVM.
I'm not sure why you'd want to have a combined artifact that can do both. You can try to copy over lib/libgraal-nodejs.so from the native distribution, but be aware that this is an untested configuration.

[mmilitzer]

@woess: Thanks for your quick reply. What concerns me about swapping out the bundled JDK is that the GraalJS 24.1.1 release notes state that "GraalJS version 24.1.1 is designed for use with Oracle GraalVM for JDK 23.0.1" - hence, can I then really swap out the bundled JDK 23 with Oracle GraalVM for JDK 21 and it'll still be compatible?

It's unfortunate that the Node.js runtime is not officially part of the Oracle GraalVM product as I assume this feature is one of the main reasons why people would consider switching to GraalVM.