quickwit-oss/quickwit · error

the snippet field `{}` must be stored

Error message

the snippet field `{}` must be stored

What it means

When a search request asks for snippets on a field, validation checks the schema entry. Snippet generation requires the original text, so the field's text options must have stored=true. If a Str field used as snippet field is not stored, this error is returned before executing the search.

Source

Thrown at quickwit/quickwit-search/src/root.rs:332

        } else {
            sort_field_is_datetime.insert(sort_field.field_name.to_string(), false);
        }
    }
    Ok(())
}

fn validate_requested_snippet_fields(
    schema: &Schema,
    snippet_fields: &[String],
) -> anyhow::Result<()> {
    for field_name in snippet_fields {
        let field_entry = schema
            .get_field(field_name)
            .map(|field| schema.get_field_entry(field))?;
        match field_entry.field_type() {
            FieldType::Str(text_options) => {
                if !text_options.is_stored() {
                    return Err(anyhow::anyhow!(
                        "the snippet field `{}` must be stored",
                        field_name
                    ));
                }
            }
            other => {
                return Err(anyhow::anyhow!(
                    "the snippet field `{}` must be of type `Str`, got `{}`",
                    field_name,
                    other.value_type().name()
                ));
            }
        }
    }
    Ok(())
}

fn simplify_search_request_for_scroll_api(req: &SearchRequest) -> crate::Result<SearchRequest> {

View on GitHub (pinned to a39730c5cd)

Solutions

  1. Set stored: true on the field's text field options in the index config and reindex (or update the index config via the API).
  2. Remove that field from the request's snippet_fields list.
  3. Choose a different stored Str field for snippet generation.

Example fix

// before (index config)
{"name": "body", "type": "text", "indexed": true, "stored": false}
// after
{"name": "body", "type": "text", "indexed": true, "stored": true}
Defensive patterns

Strategy: validation

Validate before calling

fn snippet_fields_are_stored(schema: &Schema, fields: &[String]) -> Result<(), String> {
    for f in fields {
        let entry = schema.get_field_entry(schema.get_field(f).map_err(|_| format!("unknown field {f}"))?);
        if let FieldType::Str(opts) = entry.field_type() {
            if !opts.is_stored() { return Err(format!("snippet field `{f}` must be stored")); }
        }
    }
    Ok(())
}

Type guard

fn is_stored_str_field(schema: &Schema, name: &str) -> bool {
    schema.get_field(name).map(|f| matches!(schema.get_field_entry(f).field_type(), FieldType::Str(o) if o.is_stored())).unwrap_or(false)
}

Try / catch

match search_request(snippet_fields).await {
    Err(e) if e.to_string().contains("must be stored") => search_request(&[]).await, // retry without snippets
    r => r,
}

Prevention

When it happens

Trigger: Calling search (REST or gRPC) with snippet_fields (or snippet_fields_opt) containing a field name whose schema definition is a Str field with indexing options that do not store the field.

Common situations: Adding snippet_fields to a request for a field defined only as indexed-not-stored; schema changed to drop stored=true after snippet support was added to client code; copy-pasted snippet field config from a different index.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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