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 CliInstaller.install() when status.state is 'conflict', meaning a non-Orca command already exists at the target commandPath. Orca refuses to overwrite a command it did not create to avoid clobbering a user's existing tool.

Source

Thrown at src/main/cli/cli-installer.ts:189

    const spec = await this.resolveActiveInstallSpec(defaultSpec, launcherPath)
    const baseStatus =
      spec.installMethod === 'symlink'
        ? await this.inspectSymlink(spec.commandPath, launcherPath)
        : this.isLinuxAppImage()
          ? await this.inspectAppImageWrapper(spec.commandPath, launcherPath)
          : await this.inspectWindowsWrapper(spec.commandPath, launcherPath)
    const pathDirectory = dirname(spec.commandPath)
    const pathProbe = await this.probePathConfiguration(pathDirectory)
    return this.withPathInfo(baseStatus, pathDirectory, pathProbe)
  }

  async install(): Promise<CliInstallStatus> {
    const status = await this.getStatus()
    if (!status.supported || !status.commandPath || !status.launcherPath || !status.installMethod) {
      throw new Error(status.detail ?? 'CLI registration is unavailable on this build.')
    }
    if (status.state === 'conflict') {
      throw new Error(`Refusing to replace non-Orca command at ${status.commandPath}.`)
    }

    // eslint-disable-next-line unicorn/prefer-ternary -- Why: the install path performs async side effects and is easier to audit as an explicit branch than as an awaited ternary.
    if (status.installMethod === 'symlink') {
      await this.installSymlink(status)
      await this.removeLegacyLinuxCommandIfManaged(status.launcherPath)
    } else if (this.isLinuxAppImage()) {
      await this.installAppImageWrapper(status.commandPath, status.launcherPath)
      await this.removeLegacyLinuxCommandIfManaged(status.launcherPath)
    } else if (this.isWindowsPackagedBundledCommand(status.commandPath, status.launcherPath)) {
      // Why: packaged Windows already ships resources/bin/orca.exe; registration only owns the PATH entry.
    } else {
      // Why: the Windows wrapper dir is user-writable (%LOCALAPPDATA%), so mkdir here can't hit EACCES.
      await mkdir(dirname(status.commandPath), { recursive: true })
      await this.installWindowsWrapper(status.commandPath, status.launcherPath)
    }

    if (this.platform === 'win32') {

View on GitHub (pinned to 1136503c6a)

Solutions

Check what is at status.commandPath: 'ls -la <path>' and 'file <path>'.
If it's safe to replace, manually remove or rename the conflicting file, then retry install.
If it's a different tool you need, change Orca's command name or install location if configurable.
On Linux, the rename to 'orca' from the legacy name was specifically to avoid GNOME Orca — verify the PATH order.

Defensive patterns

Strategy: validation

Validate before calling

const status = await installer.getStatus()
if (status.state === 'conflict') {
  // Do not call install(); inform user about the conflicting command
  showConflictGuidance(status.commandPath)
  return
}

Try / catch

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

Prevention

Check for existing commands at the target path before installing.
On Linux, be aware GNOME Orca screen reader may own the 'orca' name.
Clean up old installs before re-registering.

When it happens

Trigger: Another application installed a command with the same name (e.g., 'orca') at the target path. The status probe (inspectSymlink/inspectWindowsWrapper) detected the existing file is not marked with Orca's managed marker.

Common situations: GNOME Orca screen reader's 'orca' command on Linux. A different tool named 'orca' in /usr/local/bin. A previous Orca install was partially removed leaving an unmanaged file.

Related errors

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