What causes "[api] failed to launch native binary: ${errno.message}" in Yeachan-Heo/oh-my-codex?

Read the appended errno message and address that specific OS error (raise ulimit, add memory, shorten args)

Yeachan-Heo/oh-my-codex · critical · Error

[api] failed to launch native binary: ${errno.message}

Error message

[api] failed to launch native binary: ${errno.message}

What it means

A catch-all for spawn failures of the omx-api binary that are neither 'missing' (ENOENT) nor 'blocked' (EACCES/EPERM). The raw errno.message from Node's spawn error is surfaced, e.g. EMFILE, ENOMEM, E2BIG, or unsupported-platform errors.

Source

Thrown at src/cli/api.ts:223

  if (args.length === 0) return true;
  return args.includes('--help') || args.includes('-h');
}

export async function apiCommand(args: string[]): Promise<void> {
  if (isHelpRequest(args)) {
    console.log(API_USAGE);
    return;
  }

  const binaryPath = await resolveApiBinaryPathWithHydration();

  const result = runApiBinary(binaryPath, args);
  if (result.error) {
    const errno = result.error as NodeJS.ErrnoException;
    const kind = classifySpawnError(errno);
    if (kind === 'missing') throw new Error(`[api] failed to launch native binary: executable not found (${binaryPath})`);
    if (kind === 'blocked') throw new Error(`[api] failed to launch native binary: executable is blocked (${errno.code || 'blocked'})`);
    throw new Error(`[api] failed to launch native binary: ${errno.message}`);
  }

  writeApiResultOutput(result);
  if (result.status !== 0) {
    process.exitCode = typeof result.status === 'number'
      ? result.status
      : resolveSignalExitCode(result.signal);
  }
}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Read the appended errno message and address that specific OS error (raise ulimit, add memory, shorten args)
Raise file-descriptor limits: `ulimit -n 4096` before running omx
If sandboxing is the cause, run outside the sandbox or grant spawn permissions
Report the errno code to omx maintainers if it should be classified as missing/blocked

Defensive patterns

Strategy: try-catch

Validate before calling

import { ulimitCheck } from 'node:os'; // pseudo
// Raise fd limit / verify memory before spawning the binary
process.on('beforeExit', () => {});

Try / catch

catch (e) { const m = /failed to launch native binary: (.+)/.exec(String(e)); if (m) handleErrnoMessage(m[1]); else throw e; }

Prevention

Raise ulimit -n in CI shells
Keep argument lists short
Surface raw errno text to ops for triage

When it happens

Trigger: Calling `omx api` when the process cannot spawn due to resource exhaustion (EMFILE from fd limits, ENOMEM), an overlong argv (E2BIG), or platform-level spawn restrictions not classified elsewhere.

Common situations: Low ulimits in CI (`ulimit -n`), out-of-memory containers, extremely long CLI arguments, exotic sandboxed runtimes.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/b053238be2755467. Report an issue: GitHub.