warpdotdev/warp · error

unexpected argument '--environment' found

Error message

unexpected argument '--environment' found

What it means

Thrown in run_agent for AgentCommand::Run (mod.rs:269): clap accepted `--environment` (it is in the grammar), but FeatureFlag::CloudEnvironments is disabled, so the handler rejects it with an error that mimics clap's 'unexpected argument' message. The design hides optional cloud-environment targeting when the feature is gated, making the flag look unknown rather than merely disabled.

Source

Thrown at app/src/ai/agent_sdk/mod.rs:269

        ResolveSkillError::ParseFailed { path, message } => {
            format!("Failed to parse skill file {}: {message}", path.display())
        }
        ResolveSkillError::CloneFailed { org, repo, message } => {
            format!("Failed to clone repository '{org}/{repo}': {message}")
        }
    }
}

/// Run the agent with the provided command.
fn run_agent(
    ctx: &mut AppContext,
    global_options: GlobalOptions,
    command: AgentCommand,
) -> anyhow::Result<()> {
    match command {
        AgentCommand::Run(args) => {
            if args.environment.is_some() && !FeatureFlag::CloudEnvironments.is_enabled() {
                return Err(anyhow::anyhow!("unexpected argument '--environment' found"));
            }
            if args.conversation.is_some() && !FeatureFlag::CloudConversations.is_enabled() {
                return Err(anyhow::anyhow!(
                    "unexpected argument '--conversation' found"
                ));
            }
            if args.skill.is_some() && !FeatureFlag::OzPlatformSkills.is_enabled() {
                return Err(anyhow::anyhow!("unexpected argument '--skill' found"));
            }
            if args.harness != Harness::Oz && !FeatureFlag::AgentHarness.is_enabled() {
                return Err(anyhow::anyhow!("unexpected argument '--harness' found"));
            }
            if args.harness == Harness::OpenCode {
                return Err(anyhow::anyhow!(
                    "The opencode harness is only supported for local child agent launches."
                ));
            }

View on GitHub (pinned to e72fd7aacb)

Solutions

  1. Drop `--environment` and run against the default environment
  2. Use a build/account where CloudEnvironments is enabled, or update to a version where it shipped to your channel
  3. As a Warp developer, override the flag or add FeatureFlag::CloudEnvironments to DOGFOOD_FLAGS and rebuild

Example fix

# before
$ oz agent run --environment dev-box "fix the flaky test"
Error: unexpected argument '--environment' found

# after
$ oz agent run "fix the flaky test"
Defensive patterns

Strategy: validation

Validate before calling

// Rust callers building AgentCommand::Run:
if args.environment.is_some() {
    anyhow::ensure!(
        FeatureFlag::CloudEnvironments.is_enabled(),
        "--environment requires CloudEnvironments"
    );
}

Type guard

pub fn can_target_environment(args: &AgentRunArgs) -> bool {
    args.environment.is_none() || FeatureFlag::CloudEnvironments.is_enabled()
}

Try / catch

match run_agent(ctx, opts, cmd) {
    Err(e) if e.to_string().contains("unexpected argument '--environment'") => {
        // retry without --environment against the default environment
    }
    result => result?,
}

Prevention

When it happens

Trigger: Running `agent run --environment <id/prompt>` where FeatureFlag::CloudEnvironments.is_enabled() == false. The value parses into args.environment before the gate runs; only the flag state triggers the error.

Common situations: Pinning agent runs to a specific cloud environment on a build where cloud environments are gated; templates/playbooks written on dogfood builds; after a Warp downgrade that dropped the feature.

Related errors

AI-assisted analysis of warpdotdev/warp@e72fd7aacb (2026-08-16). Data as JSON: /api/errors/218cc640467dae14. Report an issue: GitHub.