heygen-com/hyperframes · error

CUDA execution provider not available. Use --device cpu or i

Error message

CUDA execution provider not available. Use --device cpu or install an onnxruntime-node build with CUDA support.

What it means

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.

Source

Thrown at packages/cli/src/background-removal/manager.ts:49

export function selectProviders(device: Device = "auto"): ProviderChoice {
  if (device === "cpu") return { providers: ["cpu"], label: "CPU" };

  const available = listAvailableProviders();
  const hasCoreML = available.includes("coreml");
  const hasCUDA = available.includes("cuda");

  if (device === "coreml") {
    if (!hasCoreML) {
      throw new Error(
        "CoreML execution provider not available. Install onnxruntime-node on Apple Silicon, or use --device cpu.",
      );
    }
    return { providers: ["coreml", "cpu"], label: "CoreML" };
  }
  if (device === "cuda") {
    if (!hasCUDA) {
      throw new Error(
        "CUDA execution provider not available. Use --device cpu or install an onnxruntime-node build with CUDA support.",
      );
    }
    return { providers: ["cuda", "cpu"], label: "CUDA" };
  }

  if (hasCoreML && platform() === "darwin" && arch() === "arm64") {
    return { providers: ["coreml", "cpu"], label: "CoreML" };
  }
  if (hasCUDA) return { providers: ["cuda", "cpu"], label: "CUDA" };
  return { providers: ["cpu"], label: "CPU" };
}

let _cachedProviders: string[] | undefined;
export function listAvailableProviders(): string[] {
  if (_cachedProviders) return _cachedProviders;

  // The npm onnxruntime-node ships with CPU on every platform and bundles the

View on GitHub (pinned to c2996c8626)

Solutions

1. Set HYPERFRAMES_CUDA=1 in the environment before launching the process.
2. Install a CUDA-enabled onnxruntime-node build and verify the GPU is present (nvidia-smi).
3. If no GPU is available, use device: 'cpu' or 'auto'.
4. Confirm CUDA toolkit and driver versions satisfy onnxruntime-node's requirements.

Example fix

// before
const session = await createSession({ device: 'cuda' }); // HYPERFRAMES_CUDA unset

// after
// export HYPERFRAMES_CUDA=1  (in shell / .env)
const session = await createSession({ device: 'cuda' });

function safeDevice(explicit?: string): 'cuda' | 'cpu' {
  if (explicit === 'cuda' && process.env.HYPERFRAMES_CUDA === '1') return 'cuda';
  return 'cpu';
}

const cudaAvailable = (): boolean => process.env.HYPERFRAMES_CUDA === '1';

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• CoreML execution provider not available. Install onnxruntime
• remove-background needs the optional native module '${name}'
• ONNX session is missing input or output bindings
• Model did not return output '${outputName}'
• ffmpeg and ffprobe are required. Install: ${getFFmpegInstall

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/57cc6f3b5c9d9841. Report an issue: GitHub.