stablyai/orca · error · RuntimeClientError

invalid_environment

invalid_environment

Error message

No coding agent detected on this host, so there is no install target. Pass --agent <name>[,<name>...] to choose targets explicitly — --agent universal writes only the shared .agents/skills directory that Orca reads.

What it means

Thrown with code `invalid_environment` (not invalid_argument) by resolveInstallAgentKeys when no coding agent was detected on the host AND the user did not pass `--agent`. Orca refuses to fall through to the skills CLI's default all-agents branch because that would create config directories for ~75 agents this machine does not have. The fix is to name a target explicitly, with `--agent universal` being the minimal choice that writes only the shared `.agents/skills` directory Orca itself reads.

Source

Thrown at src/cli/handlers/skills.ts:222

    if (unusable !== undefined) {
      // Why: the skills CLI drops a value starting with `-`, which leaves it with
      // no target and installs into every agent it knows.
      throw new RuntimeClientError(
        'invalid_argument',
        `Invalid --agent value "${unusable}". Pass agent names such as claude-code, ` +
          'codex, or universal.'
      )
    }
    return keys
  }
  const detected = detectSkillsCliAgentKeys()
  if (detected.length > 0) {
    return detected
  }
  // Why: without --agent, `skills add -y` falls into its own zero-detected branch
  // and installs into every agent it knows (~75), creating config directories for
  // agents this host does not have. Say so instead.
  throw new RuntimeClientError(
    'invalid_environment',
    'No coding agent detected on this host, so there is no install target. Pass ' +
      '--agent <name>[,<name>...] to choose targets explicitly — --agent universal ' +
      'writes only the shared .agents/skills directory that Orca reads.'
  )
}

function buildNpxSkillsArgs(
  verb: SkillMutationVerb,
  skillNames: string[],
  global: boolean,
  agents: string[]
): string[] {
  const skillArgs =
    verb === 'install'
      ? buildAgentFeatureSkillInstallArgs(skillNames, { global, yes: true, agents })
      : buildAgentFeatureSkillUpdateArgs(skillNames, { global, yes: true })
  // Why: a cold package cache makes bare `npx` prompt before it will fetch

View on GitHub (pinned to 1136503c6a)

Solutions

  1. Pass `--agent universal` to write only the shared `.agents/skills` directory Orca reads.
  2. Pass `--agent <name>` for a specific agent you intend to install on this host.
  3. Install a supported coding agent on the host so detection succeeds, then re-run without `--agent`.
  4. If this is the wrong machine entirely (e.g. an SSH-forwarded shell), see error 672.

Example fix

// before
orca skills install              // no agent detected, no --agent
// after
orca skills install --agent universal   // shared .agents/skills only
// or target a real agent
orca skills install --agent claude-code
Defensive patterns

Strategy: fallback

Validate before calling

import { detectSkillsCliAgentKeys } from '<skills>'
const detected = detectSkillsCliAgentKeys()
if (detected.length === 0 && !flags.has('agent')) {
  // provide --agent universal (or a concrete name) before invoking
}

Type guard

function needsExplicitAgent(flags: Map<string, string | boolean>, detected: string[]): boolean {
  return detected.length === 0 && !flags.has('agent')
}

Try / catch

try { await runSkillsInstall(flags) }
catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'invalid_environment' && e.message.startsWith('No coding agent detected')) {
    // retry with --agent universal (shared dir) or install a supported agent first
  } else throw e
}

Prevention

When it happens

Trigger: Running `orca skills install` (or update/add) on a machine where no known TUI coding agent is installed and `--agent` is omitted. Detection probes KNOWN_TUI_AGENT_DETECTION_COMMANDS in install dirs and finds nothing.

Common situations: Fresh machine/CI runner with Orca but no Claude Code/Codex/etc. installed; container where agent binaries aren't on PATH; SSH host whose agents live only on the client; headless server meant only to serve the shared skills dir.

Related errors

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