tursodatabase/turso · critical · UnsupportedOperationException

ARM64 architecture is not supported on Linux yet

Error message

ARM64 architecture is not supported on Linux yet

What it means

Architecture.detect() maps os.name/os.arch to a bundled native library path. Linux on aarch64/arm64 has no bundled library yet (explicit TODO in the source), so detect() throws UnsupportedOperationException. It is only reached from loadFromJar() after System.loadLibrary("_turso_java") failed, so users typically see ExceptionInInitializerError (caused by this) on the first TursoDB.create(), and NoClassDefFoundError afterwards.

Source

Thrown at bindings/java/src/main/java/tech/turso/core/TursoDB.java:71

      this.fileExtension = fileExtension;
    }

    public String getLibPath() {
      return libPath;
    }

    public String getFileExtension() {
      return fileExtension;
    }

    public static Architecture detect() {
      String osName = System.getProperty("os.name").toLowerCase();
      String osArch = System.getProperty("os.arch").toLowerCase();

      // TODO: add support for arm64 on Linux
      if (osName.contains("linux")) {
        if (osArch.contains("aarch64") || osArch.contains("arm64")) {
          throw new UnsupportedOperationException(
              "ARM64 architecture is not supported on Linux yet");
        } else if (osArch.contains("x86_64") || osArch.contains("amd64")) {
          return LINUX_X86;
        }
      }

      if (osName.contains("mac")) {
        if (osArch.contains("aarch64") || osArch.contains("arm64")) {
          return MACOS_ARM64;
        } else if (osArch.contains("x86_64") || osArch.contains("amd64")) {
          return MACOS_X86;
        }
      } else if (osName.contains("win")) {
        return WINDOWS;
      }

      return UNSUPPORTED;
    }

View on GitHub (pinned to bad083fafb)

Solutions

1. Run the JVM under x86-64 emulation: docker run --platform linux/amd64 (or set the platform in compose/CI)
2. Build lib_turso_java.so for linux aarch64 from this repository and place it on java.library.path — System.loadLibrary then succeeds in loadFromSystemPath() and loadFromJar()/detect() is never invoked
3. Move the workload to an x86_64 host/runner
4. Track upstream progress for bundled aarch64-linux artifacts

Example fix

# before: runs natively on linux/arm64 and fails
java -jar app.jar   # ExceptionInInitializerError: ARM64 architecture is not supported on Linux yet

# after: option 1 — emulate x86-64
docker run --platform linux/amd64 -v $PWD:/app eclipse-temurin:21 java -jar /app/app.jar

# after: option 2 — self-built aarch64 library on the system path
java -Djava.library.path=/opt/turso-native -jar app.jar

String os = System.getProperty("os.name").toLowerCase();
String arch = System.getProperty("os.arch").toLowerCase();
boolean linuxArm = os.contains("linux") && (arch.contains("aarch64") || arch.contains("arm64"));
if (linuxArm) {
  // pick a fallback before the first TursoDB.create: x86-64 emulation or a
  // self-built lib_turso_java.so on -Djava.library.path
}

try {
  Connection c = DriverManager.getConnection(url);
} catch (Throwable t) {
  Throwable cause = t;
  while (cause.getCause() != null) cause = cause.getCause();
  if (cause instanceof UnsupportedOperationException
      && cause.getMessage().contains("ARM64")) {
    // fail with a clear ops message: unsupported platform — needs x86-64 or a system-path native lib
  }
}

When it happens

Trigger: On linux/aarch64 or linux/arm64 (Graviton, Axion, Raspberry Pi, ARM servers), first use of TursoDB.create(...)/connection open: loadFromSystemPath() cannot find _turso_java, loadFromJar() calls Architecture.detect(), which throws before the try block.

Common situations: CI pipelines on ARM runners (GitHub Actions arm64, AWS Graviton build fleets); Docker linux/arm64 images on Apple Silicon Macs; Kubernetes clusters on ARM nodes; cross-compilation environments reporting os.arch=arm64.

Related errors

• Unable to load necessary native library
• SQLite only supports TYPE_FORWARD_ONLY cursors
• SQLite only supports CONCUR_READ_ONLY cursors
• SQLite only supports closing cursors at commit
• Cannot commit in autocommit mode.

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/d9db2eec114c83c0. Report an issue: GitHub.