heygen-com/hyperframes · error

CoreML execution provider not available. Install onnxruntime

Error message

CoreML execution provider not available. Install onnxruntime-node on Apple Silicon, or use --device cpu.

What it means

Thrown by selectProviders when the caller explicitly requests device 'coreml' but listAvailableProviders() does not include 'coreml'. CoreML is only reported as available on darwin-arm64 (Apple Silicon); on Intel Macs, Linux, or Windows the provider is absent. selectProviders is called by createSession, so this surfaces when the user passes --device coreml (or device: 'coreml') on a non-Apple-Silicon machine. The message directs the user to install onnxruntime-node on Apple Silicon or fall back to --device cpu.

Source

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

export function isDevice(value: unknown): value is Device {
  return typeof value === "string" && (DEVICES as readonly string[]).includes(value);
}

export interface ProviderChoice {
  providers: string[];
  label: "CoreML" | "CUDA" | "CPU";
}

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" };

View on GitHub (pinned to c2996c8626)

Solutions

1. Use device: 'auto' (default) — it picks CoreML on Apple Silicon and CPU elsewhere.
2. On non-Apple-Silicon, pass device: 'cpu' explicitly.
3. On Apple Silicon where it still fails, upgrade onnxruntime-node to a build that ships the CoreML EP.
4. Gate the device choice on platform()/arch() in your config.

Example fix

// before
const session = await createSession({ device: 'coreml' }); // on Linux

// after
import { platform, arch } from 'node:os';
const device = platform() === 'darwin' && arch() === 'arm64' ? 'coreml' : 'cpu';
const session = await createSession({ device });

import { platform, arch } from 'node:os';
function safeDevice(explicit?: string): 'coreml' | 'cpu' {
  if (explicit === 'coreml' && platform() === 'darwin' && arch() === 'arm64') return 'coreml';
  return 'cpu';
}

import { platform, arch } from 'node:os';
const coreMlAvailable = (): boolean =>
  platform() === 'darwin' && arch() === 'arm64';

When it happens

Trigger: Passing device: 'coreml' on an Intel Mac (arch x64), Linux, or Windows; on Apple Silicon where the onnxruntime-node build lacks the CoreML EP (older version). selectProviders checks hasCoreML from listAvailableProviders which only adds 'coreml' on darwin + arm64.

Common situations: Hardcoding --device coreml in a CI runner that is Linux-based; an Intel-Mac developer copying config from an M-series colleague; an onnxruntime-node version that doesn't bundle CoreML.

Related errors

• CUDA execution provider not available. Use --device cpu or i
• remove-background needs the optional native module '${name}'
• ONNX session is missing input or output bindings
• Model did not return output '${outputName}'
• Model download failed: ${model}

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