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

TursoDB.Architecture.detect() throws UnsupportedOperationException when os.name contains 'linux' and os.arch is aarch64 or arm64. The native library is only shipped for Linux x86_64 and macOS (x86_64 and arm64), so detection refuses immediately instead of attempting to load a nonexistent artifact. Detection runs on the path that loads the native library, so the throw surfaces at the first line of code that touches TursoDB.

Solutions

1. Force the x86_64 image: docker run --platform linux/amd64 ... (requires qemu/binfmt support on ARM hosts)
2. Run the workload where natives exist: Linux x86_64 or macOS arm64/x86_64
3. Build the native library for linux-aarch64 and install it on the system library path so the JAR path is not needed
4. Track binding updates: the source carries a TODO to add Linux ARM64 support

Example fix

# before
docker run myapp:latest        # arm64 Linux host -> UnsupportedOperationException

# after
docker run --platform linux/amd64 myapp:latest

String os = System.getProperty("os.name", "").toLowerCase(Locale.ROOT);
String arch = System.getProperty("os.arch", "").toLowerCase(Locale.ROOT);
boolean unsupportedLinuxArm = os.contains("linux")
    && (arch.contains("aarch64") || arch.contains("arm64"));
if (unsupportedLinuxArm) {
  // fail with an actionable message (or route to an x86-64 host) before touching TursoDB
  throw new IllegalStateException(
      "Linux " + arch + " has no native library; run linux/amd64 or macOS arm64");
}

try {
  TursoDB db = TursoDB.open(path);
} catch (UnsupportedOperationException e) {
  // Architecture.detect() refused the platform; report host details and stop
  log.fatal("unsupported platform: {} / {}",
      System.getProperty("os.name"), System.getProperty("os.arch"), e);
  throw e;
}

When it happens

Trigger: Running the JVM on any Linux aarch64/arm64 host: AWS Graviton instances, GitHub Actions arm64 runners, or any container with platform linux/arm64 — which is the default platform inside Docker on Apple Silicon.

Common situations: docker run on an M1/M2/M3 Mac without --platform linux/amd64; deploying the jar to Graviton EC2 or ARM Lambda; CI images migrated to arm64 runners while production stays x86_64.

Related errors

• Exception while retrieving total number of changes
• step() returned invalid result
• step() returned invalid result
• step() returned null, which is only returned when an error…
• Unable to load necessary native library

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

Appendix: 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 244cde92a7)