[sparkshell] native binary not found. Checked ${packagedCand

Error message

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

What it means

The sparkshell native binary could not be located in any search location: packaged candidate paths, the repo-local path, and the nested repo-local path. The env var OMX_SPARKSHELL_BIN_ENV can override the lookup.

Source

Thrown at src/cli/sparkshell.ts:134

  } = options;

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

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

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

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

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

export async function resolveSparkShellBinaryPathWithHydration(
  options: ResolveSparkShellBinaryPathOptions = {},
): 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 sparkshell bin env var (OMX_SPARKSHELL_BIN) to an existing binary path
Reinstall without omitting optional dependencies: `npm install` (ensure platform optional dep installed)
Check the packaged candidate paths listed in the message exist for your platform/arch; rebuild or download the native binary if missing

Example fix

# before
omx sparkshell -- echo hi
# after
OMX_SPARKSHELL_BIN=/usr/local/bin/omx-sparkshell omx sparkshell -- echo hi

Defensive patterns

Strategy: fallback

Validate before calling

import { existsSync } from 'node:fs';
const bin = process.env.OMX_SPARKSHELL_BIN;
if (!bin || !existsSync(bin)) { /* install platform optional deps or point env var at a real binary */ }

Try / catch

catch (e) { if (String(e).includes('[sparkshell] native binary not found')) { /* set OMX_SPARKSHELL_BIN or reinstall with optional deps */ } else throw e; }

Prevention

Never install with --no-optional / --omit=optional
Verify the platform binary package is present after install in CI

When it happens

Trigger: resolveSparkShellBinaryPath finding no file at any packagedSparkShellBinaryCandidatePaths entry, repoLocal, or nestedRepoLocal — typically an npm install that skipped platform optional dependencies or a git checkout without a built binary.

Common situations: `npm install --no-optional` or `--omit=optional` excluding the platform-specific binary package, unsupported platform/arch, corrupted install, or running from a repo without building the native binary.

Related errors

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