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.

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.

Appendix: 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)