stablyai/orca · error · Error

${status.detail ?? 'CLI registration is unavailable on this

Error message

${status.detail ?? 'CLI registration is unavailable on this build.'}

What it means

Thrown by CliInstaller.install() when getStatus() returns a status where supported is false, or commandPath/launcherPath/installMethod are missing. The error message uses status.detail if available (e.g., launcher missing, dev mode), otherwise falls back to a generic message.

Source

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

      }
    }

    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)

View on GitHub (pinned to 1136503c6a)

Solutions

Check status.detail and status.unsupportedReason for the specific cause.
If AppImage: move it back to its original location or re-download.
If packaged build is corrupted: reinstall Orca.
If in dev mode: run the dev launcher generation step (ensureDevLauncher) before calling install.

Defensive patterns

Strategy: validation

Validate before calling

const status = await installer.getStatus()
if (!status.supported || !status.commandPath || !status.launcherPath || !status.installMethod) {
  // Do not call install(); show status.detail to the user
  showError(status.detail ?? 'CLI registration is unavailable on this build.')
  return
}

Try / catch

try {
  await installer.install()
} catch (error) {
  if (error instanceof Error && error.message.includes('CLI registration is unavailable')) {
    // Show build/platform guidance from status.detail
  } else { throw error }
}

Prevention

Always call getStatus() before install() and check 'supported'.
Keep AppImage files in their original location after first run.
Verify the packaged build is complete before deploying.

When it happens

Trigger: Calling install() on a platform or build where the CLI launcher is not available. getStatus() returns state 'unsupported' because: the AppImage file is missing, the packaged launcher binary is absent, or development mode lacks a generated launcher.

Common situations: AppImage was moved after initial run (appImagePath is stale). Packaged build is corrupted (resources/bin/orca missing). Running install() in an unsupported environment (e.g., a CI container without electron). Dev launcher file was deleted from userData.

Related errors

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