{"record":{"id":"f77872b5ebf26cc5","repo":"Yeachan-Heo/oh-my-codex","slug":"api-native-binary-not-found-checked-packagedc","errorCode":null,"errorMessage":"[api] native binary not found. Checked ${packagedCandidates.join(', ')}, ${repoLocal}, and ${nestedRepoLocal}. Set ${OMX_API_BIN_ENV} to override the path.","messagePattern":"\\[api\\] native binary not found\\. Checked (.+?), (.+?), and (.+?)\\. Set (.+?) to override the path\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/cli/api.ts","lineNumber":130,"sourceCode":"    linuxLibcPreference,\n    exists = existsSync,\n  } = options;\n\n  const override = env[OMX_API_BIN_ENV]?.trim();\n  if (override) return isAbsolute(override) ? override : resolve(cwd, override);\n\n  for (const packaged of packagedApiBinaryCandidatePaths(packageRoot, platform, arch, env, linuxLibcPreference)) {\n    if (exists(packaged)) return packaged;\n  }\n\n  const repoLocal = repoLocalApiBinaryPath(packageRoot, platform);\n  if (exists(repoLocal)) return repoLocal;\n\n  const nestedRepoLocal = nestedRepoLocalApiBinaryPath(packageRoot, platform);\n  if (exists(nestedRepoLocal)) return nestedRepoLocal;\n\n  const packagedCandidates = packagedApiBinaryCandidatePaths(packageRoot, platform, arch, env, linuxLibcPreference);\n  throw new Error(\n    `[api] native binary not found. Checked ${packagedCandidates.join(', ')}, ${repoLocal}, and ${nestedRepoLocal}. `\n      + `Set ${OMX_API_BIN_ENV} to override the path.`,\n  );\n}\n\nexport async function resolveApiBinaryPathWithHydration(\n  options: ResolveApiBinaryPathOptions = {},\n): Promise<string> {\n  const {\n    cwd = process.cwd(),\n    env = process.env,\n    packageRoot = getPackageRoot(),\n    platform = process.platform,\n    arch = osArch(),\n    linuxLibcPreference,\n    exists = existsSync,\n  } = options;\n","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/cli/api.ts#L112-L148","documentation":"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.","triggerScenarios":"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.","commonSituations":"`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.","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"],"exampleFix":"# before\nnpm i --omit=optional omx\nomx api status\n# after\nnpm i --include=optional omx\nomx api status","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nconst bin = process.env.OMX_API_BIN;\nif (!bin || !existsSync(bin)) {\n  throw new Error('Set OMX_API_BIN to an existing omx-api binary');\n}","typeGuard":null,"tryCatchPattern":"catch (e) { if (/native binary not found/.test(String(e))) { await provisionBinaryManually(); } else throw e; }","preventionTips":["Pre-install the platform binary in Docker/CI images","Always install with optional dependencies included","Set OMX_API_BIN in locked-down environments"],"tags":["native-binary","installation","platform","api","environment-variable"],"backgroundTag":"native-binary-missing","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}