heygen-com/hyperframes · error

ONNX session is missing input or output bindings

Error message

ONNX session is missing input or output bindings

What it means

Thrown by createSession when the loaded ONNX InferenceSession has no input or output binding names (session.inputNames[0] or session.outputNames[0] is falsy). The u2net_human_seg model is expected to expose at least one named input and one named output; an empty binding list means the model file is corrupt, truncated, or not a valid ONNX graph. This fires after InferenceSession.create succeeds, so it catches models that load but have a broken graph metadata.

Source

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

    });

  let session: InferenceSession;
  let providerUsed = choice.label;
  try {
    session = await tryCreate(choice.providers);
  } catch (err) {
    if (choice.providers[0] === "cpu") throw err;
    options.onProgress?.(
      `${choice.label} provider failed (${(err as Error).message}); falling back to CPU.`,
    );
    session = await tryCreate(["cpu"]);
    providerUsed = "CPU";
  }

  const inputName = session.inputNames[0];
  const outputName = session.outputNames[0];
  if (!inputName || !outputName) {
    throw new Error("ONNX session is missing input or output bindings");
  }

  // Reused across calls; sized lazily on first frame. Saves ~9 MB/frame at 1080p.
  const inputData = new Float32Array(3 * INPUT_PLANE);
  const maskBuf = Buffer.allocUnsafe(INPUT_PLANE);
  let rgbaBuf: Buffer | null = null;
  let rgbaBgBuf: Buffer | null = null;

  return {
    provider: providerUsed,
    async process(rgb, width, height, withBackground = false) {
      const tensor = await preprocess(sharp, ort, rgb, width, height, inputData);
      const outputs = await session.run({ [inputName]: tensor });
      const output = outputs[outputName];
      if (!output) throw new Error(`Model did not return output '${outputName}'`);
      const expectedBytes = width * height * 4;
      if (!rgbaBuf || rgbaBuf.length !== expectedBytes) {
        rgbaBuf = Buffer.allocUnsafe(expectedBytes);

View on GitHub (pinned to c2996c8626)

Solutions

1. Delete the cached model and re-download: rm the file under ~/.cache/hyperframes/background-removal/models/ then re-run (ensureModel will re-fetch).
2. Verify the model file is a valid ONNX graph: load it with Python onnx.load and check graph.input/graph.output.
3. Confirm the downloaded file size matches the expected ~168 MB; a tiny file indicates truncation.
4. If supplying a custom model, ensure its graph has named input/output tensors.

Example fix

// before: truncated model in cache
// createSession() throws: missing input/output bindings

// after
rm -rf ~/.cache/hyperframes/background-removal/models
// re-run: ensureModel re-downloads the full u2net_human_seg.onnx

import { existsSync, statSync } from 'node:fs';
function assertModelIntact(path: string, minBytes = 1_000_000): void {
  if (!existsSync(path)) throw new Error('model missing');
  if (statSync(path).size < minBytes) throw new Error('model truncated');
}

try {
  await createSession();
} catch (err) {
  if (err instanceof Error && err.message.includes('missing input or output bindings')) {
    await import('node:fs').then(fs => fs.rmSync(modelPath(), { force: true }));
    await createSession(); // re-downloads
  }
}

When it happens

Trigger: A model file at modelPath(model) that is zero-byte, partially downloaded, a non-ONNX file renamed to .onnx, or an ONNX file whose graph has no named I/O. Triggered inside createSession after the session is constructed.

Common situations: A previous ensureModel download was interrupted leaving a truncated file (and the existsSync guard passed because the partial file exists); a user swapped a different model into ~/.cache/hyperframes/…/models/; an ONNX export that omitted I/O names.

Related errors

• Model did not return output '${outputName}'
• remove-background needs the optional native module '${name}'
• 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/4becf2ee5a947406. Report an issue: GitHub.