{"record":{"id":"57cc6f3b5c9d9841","repo":"heygen-com/hyperframes","slug":"cuda-execution-provider-not-available-use-devic","errorCode":null,"errorMessage":"CUDA execution provider not available. Use --device cpu or install an onnxruntime-node build with CUDA support.","messagePattern":"CUDA execution provider not available\\. Use --device cpu or install an onnxruntime-node build with CUDA support\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/background-removal/manager.ts","lineNumber":49,"sourceCode":"\nexport function selectProviders(device: Device = \"auto\"): ProviderChoice {\n  if (device === \"cpu\") return { providers: [\"cpu\"], label: \"CPU\" };\n\n  const available = listAvailableProviders();\n  const hasCoreML = available.includes(\"coreml\");\n  const hasCUDA = available.includes(\"cuda\");\n\n  if (device === \"coreml\") {\n    if (!hasCoreML) {\n      throw new Error(\n        \"CoreML execution provider not available. Install onnxruntime-node on Apple Silicon, or use --device cpu.\",\n      );\n    }\n    return { providers: [\"coreml\", \"cpu\"], label: \"CoreML\" };\n  }\n  if (device === \"cuda\") {\n    if (!hasCUDA) {\n      throw new Error(\n        \"CUDA execution provider not available. Use --device cpu or install an onnxruntime-node build with CUDA support.\",\n      );\n    }\n    return { providers: [\"cuda\", \"cpu\"], label: \"CUDA\" };\n  }\n\n  if (hasCoreML && platform() === \"darwin\" && arch() === \"arm64\") {\n    return { providers: [\"coreml\", \"cpu\"], label: \"CoreML\" };\n  }\n  if (hasCUDA) return { providers: [\"cuda\", \"cpu\"], label: \"CUDA\" };\n  return { providers: [\"cpu\"], label: \"CPU\" };\n}\n\nlet _cachedProviders: string[] | undefined;\nexport function listAvailableProviders(): string[] {\n  if (_cachedProviders) return _cachedProviders;\n\n  // The npm onnxruntime-node ships with CPU on every platform and bundles the","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/background-removal/manager.ts#L31-L67","documentation":"Thrown by selectProviders when the caller explicitly requests device 'cuda' but listAvailableProviders() does not include 'cuda'. Unlike CoreML, CUDA is gated behind an environment variable: listAvailableProviders only adds 'cuda' when process.env.HYPERFRAMES_CUDA === '1', because the default onnxruntime-node build does not bundle CUDA and binding to a missing EP throws. selectProviders is called from createSession; the message tells the user to use --device cpu or install a CUDA-enabled onnxruntime-node build.","triggerScenarios":"Passing device: 'cuda' without setting HYPERFRAMES_CUDA=1; setting it on a machine without a CUDA toolkit / GPU; using the stock onnxruntime-node (CPU-only) and expecting CUDA. The env-var gate exists precisely to avoid a binding crash against a missing EP.","commonSituations":"A GPU server where the operator forgot to export HYPERFRAMES_CUDA=1; a CI matrix entry that hardcodes --device cuda on a CPU runner; the stock onnxruntime-node npm package (no CUDA) installed where a GPU build (onnxruntime-node-gpu) is required.","solutions":["Set HYPERFRAMES_CUDA=1 in the environment before launching the process.","Install a CUDA-enabled onnxruntime-node build and verify the GPU is present (nvidia-smi).","If no GPU is available, use device: 'cpu' or 'auto'.","Confirm CUDA toolkit and driver versions satisfy onnxruntime-node's requirements."],"exampleFix":"// before\nconst session = await createSession({ device: 'cuda' }); // HYPERFRAMES_CUDA unset\n\n// after\n// export HYPERFRAMES_CUDA=1  (in shell / .env)\nconst session = await createSession({ device: 'cuda' });","handlingStrategy":"type-guard","validationCode":"function safeDevice(explicit?: string): 'cuda' | 'cpu' {\n  if (explicit === 'cuda' && process.env.HYPERFRAMES_CUDA === '1') return 'cuda';\n  return 'cpu';\n}","typeGuard":"const cudaAvailable = (): boolean => process.env.HYPERFRAMES_CUDA === '1';","tryCatchPattern":null,"preventionTips":["Set HYPERFRAMES_CUDA=1 in the environment when a GPU and CUDA-enabled onnxruntime-node are present.","Default to 'auto' or 'cpu' on CPU-only runners.","Install onnxruntime-node-gpu (CUDA build) on GPU hosts."],"tags":["onnxruntime","background-removal","cuda","device","environment"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}