stablyai/orca · error · Error

${status.detail ?? 'WSL CLI registration is unavailable.'}

Error message

${status.detail ?? 'WSL CLI registration is unavailable.'}

What it means

Thrown by WslCliInstaller.install() when getStatus() returns an unsupported status (supported is false, or commandPath/launcherPath are missing). The WSL variant of the host CLI installer's unsupported guard. Uses status.detail if available, otherwise the generic WSL message.

Source

Thrown at src/main/cli/wsl-cli-installer.ts:205

      status.commandPath &&
      (await this.isBridgeConflict(this.distro, getBridgePathFromCommandPath(status.commandPath)))
    ) {
      // Why: adopting the legacy command would fail install()'s bridge guard
      // forever; stay registered so reconciliation retries after an update.
      return { changed: false, managed: true, status }
    }

    // Why: a legacy-only managed command proves the user opted into WSL CLI
    // registration; install the current name before removing that owned script.
    return { changed: true, managed: true, status: await this.install(status) }
  }

  async install(precomputedStatus?: CliInstallStatus): Promise<CliInstallStatus> {
    // Why: repair passes its fresh probe; re-probing here would double every
    // WSL round trip on the startup reconciliation path.
    const status = precomputedStatus ?? (await this.getStatus())
    if (!status.supported || !status.commandPath || !status.launcherPath) {
      throw new Error(status.detail ?? 'WSL CLI registration is unavailable.')
    }
    if (status.state === 'conflict') {
      throw new Error(`Refusing to replace non-Orca command at ${status.commandPath}.`)
    }

    // Why: the launcher and PowerShell bridge are one registration; the
    // command replacement stays a single atomic rename (never missing for a
    // concurrent shell) while a bridge copy enables rollback of the pair.
    await this.run(
      this.distro as string,
      [
        'set -euo pipefail',
        `mkdir -p ${quoteShell(status.pathDirectory as string)}`,
        `mkdir -p ${quoteShell(getPosixDirname(getBridgePathFromCommandPath(status.commandPath)))}`,
        buildRegistrationLockPrelude(status.commandPath),
        `command_tmp=${quoteShell(`${status.commandPath}.tmp`)}.$$`,
        `bridge_path=${quoteShell(getBridgePathFromCommandPath(status.commandPath))}`,
        `legacy_command_path=${quoteShell(

View on GitHub (pinned to 1136503c6a)

Solutions

Check status.detail for the specific reason.
Verify the WSL distro is functional: 'wsl -d <distro> -- bash -lc echo ok'.
Ensure the user has write access to the target bin directory inside WSL.
Confirm the distro name is correct and still installed: 'wsl -l -v'.

Defensive patterns

Strategy: validation

Validate before calling

const status = await wslInstaller.getStatus()
if (!status.supported || !status.commandPath || !status.launcherPath) {
  showError(status.detail ?? 'WSL CLI registration is unavailable.')
  return
}

Try / catch

try {
  await wslInstaller.install()
} catch (error) {
  if (error instanceof Error && error.message.includes('WSL CLI registration is unavailable')) {
    // Show status.detail; verify distro functionality
  } else { throw error }
}

Prevention

Call getStatus() before install() and check supported flag.
Verify WSL distro has bash and writable bin directory.
Keep distro names current after WSL updates.

When it happens

Trigger: Calling install() on WSL CLI when the distro doesn't support installation, the launcher path can't be resolved, or the status probe failed. Common when WSL is present but the distro doesn't have the required tools (bash, write access to the bin directory).

Common situations: WSL distro lacks bash or has a broken PATH. The target bin directory is not writable. WSL version is too old. The PowerShell bridge path can't be resolved. Distro name is stale (uninstalled).

Related errors

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