xai-org/grok-build · error

--single: {e}

Error message

--single: {e}

What it means

PromptSource::from_args wraps failures of Self::from_text(text) as '--single: {e}'. The --single flag's raw text could not be converted into a prompt source (e.g. empty text or content that fails the text prompt invariants).

Source

Thrown at crates/codegen/xai-grok-pager/src/headless/cli.rs:46

}

#[derive(Debug, Clone)]
pub enum HeadlessPrompt {
    Text(String),
    Blocks(Vec<acp::ContentBlock>),
}

impl HeadlessPrompt {
    /// Build from mutually-exclusive CLI prompt args. `None` means interactive mode.
    pub fn from_args(
        single: Option<&str>,
        prompt_json: Option<&str>,
        prompt_file: Option<&Path>,
    ) -> anyhow::Result<Option<Self>> {
        if let Some(text) = single {
            Self::from_text(text)
                .map(Some)
                .map_err(|e| anyhow::anyhow!("--single: {e}"))
        } else if let Some(json_str) = prompt_json {
            Self::from_json(json_str)
                .map(Some)
                .map_err(|e| anyhow::anyhow!("--prompt-json: {e}"))
        } else if let Some(path) = prompt_file {
            Self::from_file(path).map(Some)
        } else {
            Ok(None)
        }
    }

    /// `.json` files are parsed as content blocks, everything else as text.
    pub fn from_file(path: &Path) -> anyhow::Result<Self> {
        let content = std::fs::read_to_string(path)
            .map_err(|e| anyhow::anyhow!("Failed to read '{}': {e}", path.display()))?;

        let context = |e| anyhow::anyhow!("'{}': {e}", path.display());
        if path.extension().and_then(|e| e.to_str()) == Some("json") {

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Ensure a non-empty prompt string is passed to --single
2. Guard the calling script: fail early if the prompt variable is empty
3. Trim intended whitespace-only input and treat it as a usage error
4. Use --prompt-file instead for long or generated prompts

Example fix

# before
pager --single "$PROMPT"   # PROMPT may be empty
# after
: "${PROMPT:?PROMPT is empty}" && pager --single "$PROMPT"

if single.trim().is_empty() {
    eprintln!("--single requires a non-empty prompt");
    std::process::exit(2);
}

fn is_usable_prompt(s: &str) -> bool { !s.trim().is_empty() }

match PromptSource::from_args(single.as_deref(), None, None) {
    Ok(Some(src)) => src,
    Ok(None) => { eprintln!("no prompt given"); std::process::exit(2); }
    Err(e) => { eprintln!("{e:#}"); std::process::exit(2); }
}

When it happens

Trigger: Calling from_args with single=Some(text) where from_text rejects the input — typically an empty or whitespace-only prompt string.

Common situations: Shell variable holding the prompt expands to empty; script passes "" when the prompt file was missing; whitespace-only flag value from templating.

Related errors

• Error: --session-id must be a valid UUID (got '{session_id}'
• {CHAT_MODE_FORK_CONFLICT}
• --header can only be used with HTTP or SSE servers.
• A URL is required for {label} servers. Usage: grok mcp add -
• Invalid URL '{url}'. Server URLs must start with http:// or

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/646cbf454c54eab8. Report an issue: GitHub.