stablyai/orca · error · Error

Codex CLI is not available in WSL ${wslInfo.distro}. Install

Error message

Codex CLI is not available in WSL ${wslInfo.distro}. Install Codex in that distro or switch Account location to Windows.

What it means

Thrown by assertWslCodexCliAvailable when the probe that runs `wsl.exe` with buildWslCodexAvailabilityArgs(distro) exits non-zero, times out (WSL_CODEX_AVAILABILITY_TIMEOUT_MS), or fails to spawn. Orca requires the Codex CLI to be installed inside the target WSL distro before it will run account/login flows there; this check fails fast with an actionable message.

Source

Thrown at src/main/codex-accounts/service.ts:1783

          )
        })
      }

      child.stdout.on('data', appendOutput)
      child.stderr.on('data', appendOutput)
      child.on('error', onError)
      child.on('close', onClose)
    })
  }

  private assertWslCodexCliAvailable(wslInfo: { distro: string; linuxPath: string }): void {
    try {
      execFileSync('wsl.exe', buildWslCodexAvailabilityArgs(wslInfo.distro), {
        encoding: 'utf-8',
        timeout: WSL_CODEX_AVAILABILITY_TIMEOUT_MS
      })
    } catch (error) {
      throw new Error(
        `Codex CLI is not available in WSL ${wslInfo.distro}. Install Codex in that distro or switch Account location to Windows.`,
        { cause: error }
      )
    }
  }

  private readIdentityFromHome(
    managedHomePath: string,
    expectedAccountId: string
  ): ResolvedCodexIdentity {
    return this.resolveIdentityFromCredentials(
      this.loadOAuthCredentials(managedHomePath, expectedAccountId)
    )
  }

  private resolveIdentityFromCredentials(
    credentials: CodexOAuthCredentials
  ): ResolvedCodexIdentity {

View on GitHub (pinned to 1136503c6a)

Solutions

Install the Codex CLI inside the WSL distro (e.g. `wsl -d <distro> -- bash -lc '<install codex>'`) and confirm `wsl -d <distro> -- codex --version` succeeds.
Switch the Account location from WSL to Windows so Orca uses the host Codex CLI instead.
Verify the distro name is correct and registered (`wsl --list`) and that codex is on the login-shell PATH.
If WSL cold-start is slow, pre-warm the distro or increase the availability timeout only after confirming codex is actually installed.

Example fix

// before: codex missing inside the distro
svc.assertWslCodexCliAvailable({ distro: 'Ubuntu', linuxPath }) // throws

// after: install codex in the distro, then retry
//   wsl -d Ubuntu -- bash -lc 'npm i -g @openai/codex ; codex --version'
svc.assertWslCodexCliAvailable({ distro: 'Ubuntu', linuxPath }) // ok

Defensive patterns

Strategy: validation

Validate before calling

import { execFileSync } from 'node:child_process'

function isCodexAvailableInDistro(distro: string): boolean {
  try {
    execFileSync('wsl.exe', ['-d', distro, '--', 'bash', '-lc', 'command -v codex >/dev/null 2>&1'], {
      encoding: 'utf-8',
      timeout: 5000
    })
    return true
  } catch {
    return false
  }
}

if (!isCodexAvailableInDistro(distro)) {
  // install codex in the distro, or switch account location to Windows
}

Type guard

function isWslCodexUnavailableError(error: unknown): boolean {
  return (
    error instanceof Error &&
    /^Codex CLI is not available in WSL /.test(error.message)
  )
}

Try / catch

try {
  svc.assertWslCodexCliAvailable({ distro, linuxPath })
} catch (error) {
  if (isWslCodexUnavailableError(error)) {
    // surface install instructions to the user, or fall back to Windows location
    await provisionWithWindowsLocation()
  } else {
    throw error
  }
}

Prevention

Pre-install the Codex CLI in every WSL distro you intend to use for accounts.
Prefer the Windows account location unless you specifically need WSL execution.
Verify with `wsl -d <distro> -- codex --version` before adding a WSL account.

When it happens

Trigger: Calling a flow that invokes assertWslCodexCliAvailable({distro, linuxPath}) when codex is not on PATH inside the distro, the distro is not installed/running, wsl.exe itself errors, or the availability probe exceeds its timeout.

Common situations: Fresh WSL distro without Codex installed; Codex installed only for the Windows host, not inside the distro; distro name typo or the distro was unregistered; slow WSL first-launch exceeding the availability timeout; PATH not exported in the distro's login shell.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/50edd2cb8957852b. Report an issue: GitHub.