[sparkshell] failed to launch native binary: executable not

Error message

[sparkshell] failed to launch native binary: executable not found (${binaryPath})

What it means

sparkshell tried to launch its native sidecar binary and spawnSync classified the failure as 'missing' (ENOENT) — and an explicit binary override (OMX sparkshell bin env var) was set, so the tmux fallback path is skipped and the error is raised directly.

Source

Thrown at src/cli/sparkshell.ts:438

    binaryPath = await resolveSparkShellBinaryPathWithHydration();
  } catch (error) {
    if (!hasExplicitOverride) {
      runSparkShellFallback(args, { cause: error, state: 'resolution-failed' });
      return;
    }
    throw error;
  }
  const result = runSparkShellBinary(binaryPath, args);

  if (result.error) {
    const errno = result.error as NodeJS.ErrnoException;
    const kind = classifySpawnError(errno);
    if (!hasExplicitOverride && (kind === 'missing' || kind === 'blocked')) {
      runSparkShellFallback(args, { cause: errno, nativePath: binaryPath, state: kind });
      return;
    }
    if (kind === 'missing') {
      throw new Error(`[sparkshell] failed to launch native binary: executable not found (${binaryPath})`);
    }
    if (kind === 'blocked') {
      throw new Error(`[sparkshell] failed to launch native binary: executable is blocked (${errno.code || 'blocked'})`);
    }
    throw new Error(`[sparkshell] failed to launch native binary: ${errno.message}`);
  }

  if (!hasExplicitOverride && isSparkShellNativeCompatibilityFailure(result)) {
    runSparkShellFallback(args, {
      cause: result.stderr || 'GLIBC-incompatible native sidecar',
      nativePath: binaryPath,
      state: 'glibc-incompatible',
    });
    return;
  }

  writeSparkShellResultOutput(result);

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Fix the override path or unset it to allow fallback: verify with `ls -l "$OMX_SPARKSHELL_BIN"`
Rebuild/reinstall the package so the bundled binary exists at the expected path
With an override, no tmux fallback occurs — ensure the path is correct or intentionally omit the override

Example fix

# before
OMX_SPARKSHELL_BIN=/opt/sparkshell/sparkshell sparkshell bash  # missing file
# after
unset OMX_SPARKSHELL_BIN
sparkshell bash

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
const bin = process.env.OMX_SPARKSHELL_BIN;
if (bin && !existsSync(bin)) throw new Error(`override binary missing: ${bin}`);

Prevention

Remember the env override disables the automatic fallback
Re-check override paths after package upgrades/relocations

When it happens

Trigger: Setting the sparkshell bin env var to a path that does not exist, then running sparkshell.

Common situations: Pointing the override at a not-yet-built binary, a stale install path after an upgrade moved the sidecar, or typos in the env var value.

Related errors

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