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

[api] native binary not found. Checked ${packagedCandidates.

Error message

[api] native binary not found. Checked ${packagedCandidates.join(', ')}, ${repoLocal}, and ${nestedRepoLocal}. Set ${OMX_API_BIN_ENV} to override the path.

What it means

The `[api]` command needs a native platform-specific binary (omx-api). `resolveApiBinaryPath` probes the packaged per-platform candidate paths, a repo-local build, and a nested repo-local build; if none exist it throws this error listing every checked location. The OMX_API_BIN_ENV environment variable can point to an explicit binary path.

Source

Thrown at src/cli/api.ts:130

    linuxLibcPreference,
    exists = existsSync,
  } = options;

  const override = env[OMX_API_BIN_ENV]?.trim();
  if (override) return isAbsolute(override) ? override : resolve(cwd, override);

  for (const packaged of packagedApiBinaryCandidatePaths(packageRoot, platform, arch, env, linuxLibcPreference)) {
    if (exists(packaged)) return packaged;
  }

  const repoLocal = repoLocalApiBinaryPath(packageRoot, platform);
  if (exists(repoLocal)) return repoLocal;

  const nestedRepoLocal = nestedRepoLocalApiBinaryPath(packageRoot, platform);
  if (exists(nestedRepoLocal)) return nestedRepoLocal;

  const packagedCandidates = packagedApiBinaryCandidatePaths(packageRoot, platform, arch, env, linuxLibcPreference);
  throw new Error(
    `[api] native binary not found. Checked ${packagedCandidates.join(', ')}, ${repoLocal}, and ${nestedRepoLocal}. `
      + `Set ${OMX_API_BIN_ENV} to override the path.`,
  );
}

export async function resolveApiBinaryPathWithHydration(
  options: ResolveApiBinaryPathOptions = {},
): Promise<string> {
  const {
    cwd = process.cwd(),
    env = process.env,
    packageRoot = getPackageRoot(),
    platform = process.platform,
    arch = osArch(),
    linuxLibcPreference,
    exists = existsSync,
  } = options;

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Set the OMX_API_BIN_ENV environment variable to the absolute path of a manually downloaded/built omx-api binary
Reinstall with optional dependencies: `npm install omx --include=optional` (or remove --omit=optional from CI config)
Verify your platform/arch/libc is actually supported (check packagedApiBinaryCandidatePaths for your platform key)
Build the binary from source in the repo so the repo-local path exists

Example fix

# before
npm i --omit=optional omx
omx api status
# after
npm i --include=optional omx
omx api status

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
const bin = process.env.OMX_API_BIN;
if (!bin || !existsSync(bin)) {
  throw new Error('Set OMX_API_BIN to an existing omx-api binary');
}

Try / catch

catch (e) { if (/native binary not found/.test(String(e))) { await provisionBinaryManually(); } else throw e; }

Prevention

Pre-install the platform binary in Docker/CI images
Always install with optional dependencies included
Set OMX_API_BIN in locked-down environments

When it happens

Trigger: Calling `resolveApiBinaryPath(...)` (or `omx api`) when the npm package omitted the platform binary (optionalDependencies not installed), the user is on an unusual platform/arch/libc combination with no candidate, or the package was installed from source without building the native binary.

Common situations: `npm install --no-optional-dependencies` or `--omit=optional` skipping the platform package; install on musl/Alpine Linux where libc detection yields no matching candidate; corrupted or partially installed node_modules; CI cache missing the binary artifact.

Related errors

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