What causes "agent run requires a non-empty query" in nikivdev/code?

Pass a non-empty prompt as positional arguments after the run subcommand

agent run requires a non-empty query

Error message

agent run requires a non-empty query

What it means

This error is thrown when the `f agent run`-style CLI subcommand is invoked without any effective query text. The command joins the variadic `query` arguments with spaces and trims the result; if the result is empty (no args, or only whitespace), the command refuses to start an agent run. It exists to fail fast before spawning the codex agent bridge.

Source

Thrown at src/ai.rs:11303

        CodexAgentAction::Show { agent_id } => {
            let output = run_agent_router_show(&agent_id)?;
            print!("{output}");
            if !output.ends_with('\n') {
                println!();
            }
            Ok(())
        }
        CodexAgentAction::Run {
            path,
            new_thread,
            json,
            agent_id,
            query,
        } => {
            let target_path = resolve_session_target_path(path.as_deref())?;
            let query_text = query.join(" ").trim().to_string();
            if query_text.is_empty() {
                bail!("agent run requires a non-empty query");
            }
            let repo_root = detect_git_root(&target_path).unwrap_or_else(|| target_path.clone());
            let completed =
                run_codex_agent_bridge(&agent_id, &target_path, new_thread, &query_text)?;
            record_run_agent_bridge_activity(&agent_id, &target_path, &repo_root, &completed);
            if json {
                println!(
                    "{}",
                    serde_json::to_string_pretty(&completed)
                        .context("failed to encode codex agent run JSON")?
                );
            } else {
                print_run_agent_completed_event(&completed);
            }
            Ok(())
        }
    }
}

View on GitHub (pinned to a747e741ae)

Solutions

Pass a non-empty prompt as positional arguments after the run subcommand
Check that any shell variable used for the prompt is non-empty before invoking
Quote the prompt so whitespace survives shell splitting

Example fix

// before
f my-agent run "$PROMPT"   # PROMPT is empty -> bail!
// after
[ -n "$PROMPT" ] && f my-agent run "$PROMPT"

Defensive patterns

Strategy: validation

Validate before calling

let query_text = query.join(" ").trim().to_string();
if query_text.is_empty() {
    eprintln!("agent run requires a non-empty query");
    std::process::exit(2);
}

Type guard

fn has_query(args: &[String]) -> bool {
    !args.join(" ").trim().is_empty()
}

Prevention

Always pass the prompt as quoted positional args
Guard shell variables with ${PROMPT:?unset} before invoking
Add a smoke test asserting the command fails fast on empty query

When it happens

Trigger: Calling the agent run subcommand with no positional query words, or with query arguments consisting only of whitespace (e.g. `f <agent> run --agent my-agent " "`).

Common situations: Scripting the CLI where a shell variable holding the prompt is empty or unset; quoting mistakes that drop the prompt argument; copy-pasting a command template without filling in the query.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/40d02760fc0400cf. Report an issue: GitHub.