stablyai/orca · error · Error

Refusing to replace non-Orca command at ${status.commandPath

Error message

Refusing to replace non-Orca command at ${status.commandPath}.

What it means

Thrown by WslCliInstaller.install() when status.state is 'conflict' — a non-Orca command exists at the target commandPath inside the WSL distro. The WSL equivalent of the host installer's conflict guard.

Source

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

      // 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(
          `${getPosixDirname(status.commandPath)}/${LEGACY_WSL_COMMAND_NAME}`
        )}`,
        'bridge_tmp="${bridge_path}.tmp.$$"',

View on GitHub (pinned to 1136503c6a)

Solutions

Inside WSL, check the conflicting file: 'wsl -d <distro> -- cat <commandPath>' and look for Orca markers.
If safe, remove the conflicting file inside WSL and retry.
If it's a tool you need, install Orca CLI under a different name or path.

Defensive patterns

Strategy: validation

Validate before calling

const status = await wslInstaller.getStatus()
if (status.state === 'conflict') {
  showConflictGuidance(status.commandPath)
  return
}

Try / catch

try {
  await wslInstaller.install()
} catch (error) {
  if (error instanceof Error && error.message.includes('Refusing to replace non-Orca command')) {
    // Prompt user to remove conflicting file inside WSL
  } else { throw error }
}

Prevention

Check for existing commands at the target path inside WSL before installing.
Document that Orca checks managed markers before overwriting.

When it happens

Trigger: Calling install() when another command (not Orca-managed) exists at the target path inside the WSL distro. The buildSafeReplaceGuard check in the bash install script detects the foreign command.

Common situations: A different 'orca' binary was installed in the WSL distro's bin directory. A legacy Orca command without the managed marker. Another package manager (apt, brew in WSL) installed a conflicting binary.

Related errors

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