[sparkshell] raw fallback failed: executable not found (${in

Error message

[sparkshell] raw fallback failed: executable not found (${invocation.argv[0]})

What it means

The sparkshell fallback path tried to spawn the resolved program (invocation.argv[0], e.g. `tmux`) via spawnSync and got ENOENT-classified error: the executable is not on PATH or does not exist. The fallback is only reached after the native sparkshell binary also failed to launch.

Source

Thrown at src/cli/sparkshell.ts:392

}

function runSparkShellFallback(args: readonly string[], options: RunSparkShellFallbackOptions = {}): void {
  const { announce = true, cause = 'native sidecar unavailable', nativePath = 'native-resolution', state = 'unavailable' } = options;
  const invocation = parseSparkShellFallbackInvocation(args);
  if (announce) {
    process.stderr.write(`[sparkshell] native sidecar unavailable; cause=${sanitizeFallbackDiagnostic(cause)}; path=${sanitizeFallbackDiagnostic(nativePath)}; state=${sanitizeFallbackDiagnostic(state)}; remediation=install a compatible native sidecar, reconnect for hydration, or set ${OMX_SPARKSHELL_BIN_ENV}. Falling back to raw command execution without summary support.\n`);
  }
  const result = spawnSync(invocation.argv[0], invocation.argv.slice(1), {
    cwd: process.cwd(),
    env: process.env,
    stdio: 'inherit',
    encoding: 'utf-8',
  });
  if (result.error) {
    const errno = result.error as NodeJS.ErrnoException;
    const kind = classifySpawnError(errno);
    if (kind === 'missing') {
      throw new Error(`[sparkshell] raw fallback failed: executable not found (${invocation.argv[0]})`);
    }
    if (kind === 'blocked') {
      throw new Error(`[sparkshell] raw fallback failed: executable is blocked (${errno.code || 'blocked'})`);
    }
    throw new Error(`[sparkshell] raw fallback failed: ${errno.message}`);
  }
  if (result.status !== 0) {
    process.exitCode = typeof result.status === 'number'
      ? result.status
      : resolveSignalExitCode(result.signal);
  }
}

export async function sparkshellCommand(args: string[]): Promise<void> {
  if (args[0] === '--help' || args[0] === '-h') {
    console.log(SPARKSHELL_USAGE);
    return;
  }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Install tmux (`apt-get install tmux` / `brew install tmux`)
Verify PATH includes tmux: `which tmux` in the same shell/environment that runs sparkshell
Set the sparkshell binary env override so the native path is used instead of falling back

Example fix

# before (tmux missing)
sparkshell --tmux-pane 0
# after
apt-get install -y tmux
sparkshell --tmux-pane 0

Defensive patterns

Strategy: validation

Validate before calling

import { spawnSync } from 'node:child_process';
const probe = spawnSync('tmux', ['-V'], { encoding: 'utf-8' });
if (probe.error) throw new Error('tmux not available on PATH');

Prevention

Probe for tmux with `tmux -V` before using pane mode in scripts
Ensure CI images install tmux if pane capture is used

When it happens

Trigger: No tmux installed (or not in PATH of the sparkshell process) while using --tmux-pane mode after the native binary failed.

Common situations: Minimal containers/CI images without tmux; PATH stripped or overridden when invoking node; nvm/asdf shims hiding tmux.

Related errors

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