Description
The prebuilt @node-llama-cpp/mac-arm64-metal binary (v3.16.0, llama.cpp b8095) uses MTLResidencySetDescriptor which was introduced in macOS 15 (Sequoia). On macOS 14 (Sonoma), the Metal backend fails to load silently — getLlama({ gpu: "metal" }) returns gpu: false without any error, falling back to CPU.
Environment
- macOS: 14.6.1 (Sonoma), Darwin 23.6.0
- Hardware: Apple M1 Pro
- node-llama-cpp: 3.16.0
- Node.js: 22.22.0
Steps to Reproduce
import { getLlama, LlamaLogLevel } from "node-llama-cpp";
const llama = await getLlama({ gpu: "metal", logLevel: LlamaLogLevel.debug });
console.log("GPU:", llama.gpu); // falseDebug log shows BLAS and CPU backends loading, but Metal is never loaded.
Root Cause
dlopen of libggml-metal.so fails:
Symbol not found: _OBJC_CLASS_$_MTLResidencySetDescriptor
Referenced from: libggml-metal.so (built for macOS 26.0 which is newer than running OS)
Expected in: /System/Library/Frameworks/Metal.framework/Versions/A/Metal
MTLResidencySetDescriptor is a macOS 15+ API. The prebuilt binary's deployment target is too high for macOS 14.
Workaround
Rebuilding locally fixes it — the local build targets the host SDK:
npx node-llama-cpp source download --gpu metal
After rebuild, Metal works correctly (GPU offloading, full VRAM).
Suggestion
Set a lower CMAKE_OSX_DEPLOYMENT_TARGET (e.g. 14.0) when building the prebuilt Metal binaries in CI, so they work across supported macOS versions.
Related
Description
The prebuilt
@node-llama-cpp/mac-arm64-metalbinary (v3.16.0, llama.cpp b8095) usesMTLResidencySetDescriptorwhich was introduced in macOS 15 (Sequoia). On macOS 14 (Sonoma), the Metal backend fails to load silently —getLlama({ gpu: "metal" })returnsgpu: falsewithout any error, falling back to CPU.Environment
Steps to Reproduce
Debug log shows BLAS and CPU backends loading, but Metal is never loaded.
Root Cause
dlopenoflibggml-metal.sofails:MTLResidencySetDescriptoris a macOS 15+ API. The prebuilt binary's deployment target is too high for macOS 14.Workaround
Rebuilding locally fixes it — the local build targets the host SDK:
npx node-llama-cpp source download --gpu metalAfter rebuild, Metal works correctly (GPU offloading, full VRAM).
Suggestion
Set a lower
CMAKE_OSX_DEPLOYMENT_TARGET(e.g.14.0) when building the prebuilt Metal binaries in CI, so they work across supported macOS versions.Related