heygen-com/hyperframes · error

remove-background needs the optional native module '${name}'

Error message

remove-background needs the optional native module '${name}', which isn't available (${(err as Error).message}). Install it with `npm i ${name}`, or reinstall hyperframes with optional dependencies enabled.

What it means

Thrown by loadNative in the background-removal inference module when the dynamic import of onnxruntime-node or sharp rejects. Both are optional native dependencies whose platform binaries don't install everywhere (Alpine/musl, some ARM Linux, CI with --omit=optional). loadNative wraps the raw 'Cannot find module' or 'Module did not self-register' error with an actionable install hint naming the missing module. The message tells the user exactly which package to install and that optional dependencies must be enabled.

Source

Thrown at packages/cli/src/background-removal/inference.ts:62

  ): Promise<SessionResult>;
  provider: string;
  close(): Promise<void>;
}

export interface CreateSessionOptions {
  model?: ModelId;
  device?: Device;
  onProgress?: (message: string) => void;
}

// onnxruntime-node and sharp are optional native modules — their platform
// binaries don't install everywhere. Surface an actionable error instead of a
// raw "Cannot find module" when one can't load.
async function loadNative<T>(name: string, load: () => Promise<T>): Promise<T> {
  try {
    return await load();
  } catch (err) {
    throw new Error(
      `remove-background needs the optional native module '${name}', which isn't available ` +
        `(${(err as Error).message}). Install it with \`npm i ${name}\`, or reinstall hyperframes with optional dependencies enabled.`,
    );
  }
}

export async function createSession(options: CreateSessionOptions = {}): Promise<Session> {
  const ort = (await loadNative(
    "onnxruntime-node",
    () => import("onnxruntime-node"),
  )) as unknown as OrtModule;
  const sharp = (await loadNative("sharp", () => import("sharp"))).default as Sharp;

  const choice = selectProviders(options.device ?? "auto");
  const path = await ensureModel(options.model, { onProgress: options.onProgress });

  options.onProgress?.(`Loading model on ${choice.label}...`);

View on GitHub (pinned to c2996c8626)

Solutions

1. Install the missing module explicitly: npm i onnxruntime-node sharp (or the one named in the message).
2. Reinstall hyperframes with optional dependencies enabled (remove --no-optional / --omit=optional).
3. On Alpine/musl, switch to a glibc-based image or build the native modules from source with the required toolchain.
4. After a Node upgrade, rebuild native addons: npm rebuild.

Example fix

// before
npm i --omit=optional hyperframes
// createSession() throws: needs 'sharp'

// after
npm i sharp onnxruntime-node
// or: npm i hyperframes  (without --omit=optional)

async function canImport(name: string): Promise<boolean> {
  try { await import(name); return true; } catch { return false; }
}
// before background removal:
if (!(await canImport('sharp')) || !(await canImport('onnxruntime-node'))) {
  throw new Error('run: npm i sharp onnxruntime-node');
}

try {
  await createSession();
} catch (err) {
  if (err instanceof Error && err.message.includes('optional native module')) {
    console.error('Install native deps and retry: npm i sharp onnxruntime-node');
  }
  throw err;
}

When it happens

Trigger: createSession() triggers loadNative for onnxruntime-node then sharp. Either import fails because the package was skipped during install (optionalDependencies not fetched), the platform binary is incompatible, or the native addon failed to load against the system's shared libraries (libvips, libc++).

Common situations: Installing with npm i --omit=optional or bun install with optional deps disabled; running on Alpine (musl) where prebuilt sharp/onnxruntime glibc binaries don't load; a Node version mismatch (ABI) after an upgrade; a corrupted node_modules after a partial install.

Related errors

• ONNX session is missing input or output bindings
• Model did not return output '${outputName}'
• CoreML execution provider not available. Install onnxruntime
• CUDA execution provider not available. Use --device cpu or i
• Model download failed: ${model}

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