quickwit-oss/quickwit · error

The user query should be valid.

Error message

The user query should be valid.

What it means

qast_helper converts user query text into a parsed QueryAST and asserts the query is valid with .expect("The user query should be valid."). It's a convenience/test helper: if query_ast_from_user_text(...).parse_user_query(&[]) returns an error (invalid query syntax, unknown field, bad aggregation, etc.) the helper panics instead of returning the error. Callers such as DeleteQuery parsing and qast_json_helper rely on it.

Source

Thrown at quickwit/quickwit-query/src/query_ast/mod.rs:325

/// The resolution assumes that there are no default search fields
/// in the doc mapper.
///
/// # Panics
///
/// Panics if the user text is invalid.
pub fn qast_json_helper(user_text: &str, default_fields: &[&'static str]) -> String {
    let ast = qast_helper(user_text, default_fields);
    serde_json::to_string(&ast).expect("The query AST should be JSON serializable.")
}

pub fn qast_helper(user_text: &str, default_fields: &[&'static str]) -> QueryAst {
    let default_fields: Vec<String> = default_fields
        .iter()
        .map(|default_field| default_field.to_string())
        .collect();
    query_ast_from_user_text(user_text, Some(default_fields))
        .parse_user_query(&[])
        .expect("The user query should be valid.")
}

/// Creates a QueryAST with a single UserInputQuery node.
///
/// Disclaimer:
/// At this point the query has not been parsed.
///
/// The actual parsing is meant to happen on a root node,
/// `default_fields` can be passed to decide which field should be search
/// if not specified specifically in the user query (e.g. hello as opposed to "body:hello").
///
/// If it is not supplied, the docmapper search fields are meant to be used.
///
/// If no boolean operator is specified, the default is `AND` (contrary to the Elasticsearch
/// default).
pub fn query_ast_from_user_text(user_text: &str, default_fields: Option<Vec<String>>) -> QueryAst {
    UserInputQuery {
        user_text: user_text.to_string(),

View on GitHub (pinned to a39730c5cd)

Solutions

1. Fix the query text: validate syntax and field names against the index schema before calling the API.
2. If this is your own code path, replace the expect with proper error propagation (return anyhow::Result) so callers get a descriptive 400-style error instead of a panic.
3. For DeleteQuery flows, test the query with a search first to confirm it parses against your index configuration (default fields, schemas).

Example fix

// before
query_ast_from_user_text(user_text, Some(default_fields))
    .parse_user_query(&[])
    .expect("The user query should be valid.")
// after
query_ast_from_user_text(user_text, Some(default_fields))
    .parse_user_query(&[])
    .context("invalid user query")?

// validate before submitting
def search_query_ok(q: str) -> bool: return bool(q.strip()) and q.count('"') % 2 == 0 and q.count('(') == q.count(')')

// Rust helper usage
match query_ast_from_user_text(user_text, Some(default_fields)).parse_user_query(&[]) {
    Ok(qast) => qast,
    Err(e) => return Err(anyhow::anyhow!("invalid user query: {e}")),
}

When it happens

Trigger: Passing user_text that fails parse_user_query: malformed query DSL syntax (e.g. unbalanced quotes/parentheses), invalid field names/types, unsupported aggregation or sort field, or an empty/invalid query string reaching DeleteQuery parsing or qast_json_helper.

Common situations: Sending a delete query with bad syntax through the REST/gRPC delete API; programmatically building query ASTs with hand-written JSON that references nonexistent or mistyped fields; upgrading quickwit where a previously valid query syntax is now rejected.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

• node not found in pending
• OTP logs or traces do not support VRL transforms
• `doc_batch` should not be empty
• failed to parse query: `{}`
• err_msg

AI-assisted analysis of quickwit-oss/quickwit@a39730c5cd (2026-09-08). Data as JSON: /api/errors/6539357131418dd3. Report an issue: GitHub.