What causes "[sparkshell] raw fallback failed: ${errno.message}" in Yeachan-Heo/oh-my-codex?

Read the embedded errno message to identify the OS failure

[sparkshell] raw fallback failed: ${errno.message}

Error message

[sparkshell] raw fallback failed: ${errno.message}

What it means

spawnSync returned an error in the fallback path that is neither 'missing' (ENOENT) nor 'blocked' (EACCES-style); the raw Node error message is surfaced. This is the catch-all for spawn failures such as EINVAL, EIO, or EMFILE.

Source

Thrown at src/cli/sparkshell.ts:397

  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;
  }

  if (args.length === 0) {
    throw new Error(`Missing command to run.\n${SPARKSHELL_USAGE}`);
  }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Read the embedded errno message to identify the OS failure
Check `ulimit -n` and raise it if EMFILE
Reproduce outside sparkshell: `node -e "require('child_process').spawnSync(process.argv[1],[])" tmux`

Defensive patterns

Strategy: try-catch

Try / catch

try {
  runSparkShellFallback(invocation);
} catch (e) {
  const msg = (e as Error).message;
  if (msg.includes('ENOENT')) installTmux();
  else if (msg.includes('EACCES')) fixPerms();
  else throw e;
}

Prevention

Surface the embedded errno message to users for actionable guidance
Retry only after fixing the underlying OS condition, not blindly

When it happens

Trigger: Corrupt argv, OS-level resource exhaustion (EMFILE), or exotic spawn errors when launching the fallback program.

Common situations: Very low ulimits in CI, broken shebangs, node/runtime version edge cases.

Related errors

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