{"record":{"id":"d9db2eec114c83c0","repo":"tursodatabase/turso","slug":"arm64-architecture-is-not-supported-on-linux-yet","errorCode":null,"errorMessage":"ARM64 architecture is not supported on Linux yet","messagePattern":"ARM64 architecture is not supported on Linux yet","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"critical","filePath":"bindings/java/src/main/java/tech/turso/core/TursoDB.java","lineNumber":71,"sourceCode":"      this.fileExtension = fileExtension;\n    }\n\n    public String getLibPath() {\n      return libPath;\n    }\n\n    public String getFileExtension() {\n      return fileExtension;\n    }\n\n    public static Architecture detect() {\n      String osName = System.getProperty(\"os.name\").toLowerCase();\n      String osArch = System.getProperty(\"os.arch\").toLowerCase();\n\n      // TODO: add support for arm64 on Linux\n      if (osName.contains(\"linux\")) {\n        if (osArch.contains(\"aarch64\") || osArch.contains(\"arm64\")) {\n          throw new UnsupportedOperationException(\n              \"ARM64 architecture is not supported on Linux yet\");\n        } else if (osArch.contains(\"x86_64\") || osArch.contains(\"amd64\")) {\n          return LINUX_X86;\n        }\n      }\n\n      if (osName.contains(\"mac\")) {\n        if (osArch.contains(\"aarch64\") || osArch.contains(\"arm64\")) {\n          return MACOS_ARM64;\n        } else if (osArch.contains(\"x86_64\") || osArch.contains(\"amd64\")) {\n          return MACOS_X86;\n        }\n      } else if (osName.contains(\"win\")) {\n        return WINDOWS;\n      }\n\n      return UNSUPPORTED;\n    }","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/java/src/main/java/tech/turso/core/TursoDB.java#L53-L89","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run the JVM under x86-64 emulation: docker run --platform linux/amd64 (or set the platform in compose/CI)","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","Move the workload to an x86_64 host/runner","Track upstream progress for bundled aarch64-linux artifacts"],"exampleFix":"# before: runs natively on linux/arm64 and fails\njava -jar app.jar   # ExceptionInInitializerError: ARM64 architecture is not supported on Linux yet\n\n# after: option 1 — emulate x86-64\ndocker run --platform linux/amd64 -v $PWD:/app eclipse-temurin:21 java -jar /app/app.jar\n\n# after: option 2 — self-built aarch64 library on the system path\njava -Djava.library.path=/opt/turso-native -jar app.jar","handlingStrategy":"fallback","validationCode":"String os = System.getProperty(\"os.name\").toLowerCase();\nString arch = System.getProperty(\"os.arch\").toLowerCase();\nboolean linuxArm = os.contains(\"linux\") && (arch.contains(\"aarch64\") || arch.contains(\"arm64\"));\nif (linuxArm) {\n  // pick a fallback before the first TursoDB.create: x86-64 emulation or a\n  // self-built lib_turso_java.so on -Djava.library.path\n}","typeGuard":null,"tryCatchPattern":"try {\n  Connection c = DriverManager.getConnection(url);\n} catch (Throwable t) {\n  Throwable cause = t;\n  while (cause.getCause() != null) cause = cause.getCause();\n  if (cause instanceof UnsupportedOperationException\n      && cause.getMessage().contains(\"ARM64\")) {\n    // fail with a clear ops message: unsupported platform — needs x86-64 or a system-path native lib\n  }\n}","preventionTips":["Pin CI/deployment images to linux/amd64 where the bundled native library is required","Detect os.name/os.arch at startup and fail with an explicit message before any DB call","If ARM hardware is mandatory, pre-build the native library and ship it on java.library.path"],"tags":["java","native-library","arm64","aarch64","platform","bindings"],"backgroundTag":"unsupported-cpu-architecture","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}