What causes "Unknown or unsupported arch: %s" in oracle/graal?

Run on a supported architecture (x86_64/amd64, aarch64, riscv64) with the matching GraalVM build.

oracle/graal · error · GraalError

Unknown or unsupported arch: %s

Error message

Unknown or unsupported arch: %s

What it means

On the libgraal host side, GraalServices.getJVMCIArch() maps the raw os.arch system property to a Graal Architecture name. Only x86_64/amd64, aarch64, and riscv64 are recognized; any other value (ppc64le, s390x, arm, or a bogus os.arch) throws GraalError('Unknown or unsupported arch').

Source

Thrown at compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/serviceprovider/GraalServices.java:88

            return GraalServices.class.getClassLoader().loadClass(name);
        } catch (Throwable e) {
            return null;
        }
    }

    /**
     * Gets a name for the current architecture that is compatible with
     * {@link Architecture#getName()}.
     */
    @LibGraalSupport.HostedOnly
    private static String getJVMCIArch() {
        String rawArch = getSavedProperty("os.arch");
        return switch (rawArch) {
            case "x86_64" -> "AMD64";
            case "amd64" -> "AMD64";
            case "aarch64" -> "aarch64";
            case "riscv64" -> "riscv64";
            default -> throw new GraalError("Unknown or unsupported arch: %s", rawArch);
        };
    }

    @LibGraalSupport.HostedOnly
    @SuppressWarnings("unchecked")
    private static void addProviders(String arch, Class<?> service) {
        List<Object> providers = (List<Object>) GraalServices.libgraalServices.computeIfAbsent(service, key -> new ArrayList<>());
        for (Object provider : ServiceLoader.load(service, GraalServices.class.getClassLoader())) {
            if (provider instanceof ArchitectureSpecific as && !as.getArchitecture().equals(arch)) {
                // Skip provider for another architecture
                continue;
            }
            if (provider.getClass().getAnnotation(LibGraalSupport.HostedOnly.class) != null) {
                // Skip hosted-only providers
                continue;
            }
            providers.add(provider);
        }

View on GitHub (pinned to a66e9ccd1d)

Solutions

Run on a supported architecture (x86_64/amd64, aarch64, riscv64) with the matching GraalVM build.
On community-arch hardware, use the community GraalVM build for that arch or disable libgraal/the Graal JIT as applicable.
Print System.getProperty('os.arch') in the failing environment to confirm what the JVM reports.

Defensive patterns

Strategy: validation

Validate before calling

// Gate Graal/libgraal initialization on a recognized architecture
static boolean archSupported() {
    return switch (System.getProperty("os.arch")) {
        case "x86_64", "amd64", "aarch64", "riscv64" -> true;
        default -> false;
    };
}
if (!archSupported()) {
    throw new IllegalStateException("Unsupported os.arch=" + System.getProperty("os.arch") + " for GraalVM");
}

Prevention

Pin CI and deployment images to supported architectures (x86_64, aarch64, riscv64).
Document the arch matrix for your project; add a startup guard that fails fast with a clear message before Graal initializes.

When it happens

Trigger: Initializing libgraal/GraalVM compiler services on hardware outside the supported list, or in an environment where os.arch is set to an unexpected string.

Common situations: Running on community-ported architectures (ppc64le, s390x) with a stock GraalVM build; CI runners reporting unusual os.arch values; cross-compilation or container environments with misreported architecture.

Related errors

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