{"record":{"id":"00f354664dc28c74","repo":"heygen-com/hyperframes","slug":"remove-background-needs-the-optional-native-module","errorCode":null,"errorMessage":"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.","messagePattern":"remove-background needs the optional native module '(.+?)', which isn't available \\((.+?)\\)\\. Install it with `npm i (.+?)`, or reinstall hyperframes with optional dependencies enabled\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/background-removal/inference.ts","lineNumber":62,"sourceCode":"  ): Promise<SessionResult>;\n  provider: string;\n  close(): Promise<void>;\n}\n\nexport interface CreateSessionOptions {\n  model?: ModelId;\n  device?: Device;\n  onProgress?: (message: string) => void;\n}\n\n// onnxruntime-node and sharp are optional native modules — their platform\n// binaries don't install everywhere. Surface an actionable error instead of a\n// raw \"Cannot find module\" when one can't load.\nasync function loadNative<T>(name: string, load: () => Promise<T>): Promise<T> {\n  try {\n    return await load();\n  } catch (err) {\n    throw new Error(\n      `remove-background needs the optional native module '${name}', which isn't available ` +\n        `(${(err as Error).message}). Install it with \\`npm i ${name}\\`, or reinstall hyperframes with optional dependencies enabled.`,\n    );\n  }\n}\n\nexport async function createSession(options: CreateSessionOptions = {}): Promise<Session> {\n  const ort = (await loadNative(\n    \"onnxruntime-node\",\n    () => import(\"onnxruntime-node\"),\n  )) as unknown as OrtModule;\n  const sharp = (await loadNative(\"sharp\", () => import(\"sharp\"))).default as Sharp;\n\n  const choice = selectProviders(options.device ?? \"auto\");\n  const path = await ensureModel(options.model, { onProgress: options.onProgress });\n\n  options.onProgress?.(`Loading model on ${choice.label}...`);\n","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/background-removal/inference.ts#L44-L80","documentation":"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.","triggerScenarios":"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++).","commonSituations":"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.","solutions":["Install the missing module explicitly: npm i onnxruntime-node sharp (or the one named in the message).","Reinstall hyperframes with optional dependencies enabled (remove --no-optional / --omit=optional).","On Alpine/musl, switch to a glibc-based image or build the native modules from source with the required toolchain.","After a Node upgrade, rebuild native addons: npm rebuild."],"exampleFix":"// before\nnpm i --omit=optional hyperframes\n// createSession() throws: needs 'sharp'\n\n// after\nnpm i sharp onnxruntime-node\n// or: npm i hyperframes  (without --omit=optional)","handlingStrategy":"fallback","validationCode":"async function canImport(name: string): Promise<boolean> {\n  try { await import(name); return true; } catch { return false; }\n}\n// before background removal:\nif (!(await canImport('sharp')) || !(await canImport('onnxruntime-node'))) {\n  throw new Error('run: npm i sharp onnxruntime-node');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await createSession();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('optional native module')) {\n    console.error('Install native deps and retry: npm i sharp onnxruntime-node');\n  }\n  throw err;\n}","preventionTips":["Install without --omit=optional / --no-optional so optionalDependencies fetch.","On Alpine/musl, use a glibc-based image or build sharp/onnxruntime-node from source.","Run npm rebuild after a Node version upgrade to recompile native addons."],"tags":["native-module","background-removal","onnxruntime","sharp","dependency"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}