infiniflow/ragflow · error · ValueError

Querit chunks_per_doc must be an integer from 1 to 3.

Error message

Querit chunks_per_doc must be an integer from 1 to 3.

What it means

ValueError from _validate_search_inputs(): the optional 'chunks_per_doc' parameter must be None or a strict int in [1, 3]. Floats, strings, booleans, zero, or values above 3 raise. It is the only search input that may be omitted (None passes).

Source

Thrown at agent/tools/querit.py:408

    if "results" in response_data and not isinstance(response_data["results"], list):
        raise TypeError("Querit API response field results must be an array.")
    if "statuses" in response_data and not isinstance(response_data["statuses"], list):
        raise TypeError("Querit API response field statuses must be an array.")


def _validate_search_inputs(
    count: Any,
    chunks_per_doc: Any,
    time_range: Any,
    site_include: Any,
    site_exclude: Any,
    country_include: Any,
    language_include: Any,
) -> None:
    if type(count) is not int or count < 1:
        raise ValueError("Querit count must be an integer greater than or equal to 1.")
    if chunks_per_doc is not None and (type(chunks_per_doc) is not int or not 1 <= chunks_per_doc <= 3):
        raise ValueError("Querit chunks_per_doc must be an integer from 1 to 3.")
    if type(time_range) is not str:
        raise ValueError("Querit time_range must be a string.")
    if time_range and not TIME_RANGE_PATTERN.fullmatch(time_range):
        raise ValueError("Querit time_range must use dN, wN, mN, yN, or YYYY-MM-DDtoYYYY-MM-DD.")
    for name, value in (
        ("site_include", site_include),
        ("site_exclude", site_exclude),
        ("country_include", country_include),
        ("language_include", language_include),
    ):
        if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
            raise ValueError(f"Querit {name} must be an array of strings.")


def _safe_error_message(error: Exception, api_key: str) -> str:
    message = str(error) or error.__class__.__name__
    return message.replace(api_key, "[REDACTED]") if api_key else message

View on GitHub (pinned to 554fb1133a)

Solutions

1. Use an integer 1, 2, or 3 — or pass None / omit the parameter entirely.
2. Clamp in your caller: chunks_per_doc = None if not value else max(1, min(3, int(value))).
3. Use 0-to-mean-unset templates remapped to None before the call.

Example fix

# before
chunks_per_doc = 5  # ValueError

# after
chunks_per_doc = 3 if value > 3 else (value or None)  # capped at 3, None when unset

def safe_chunks_per_doc(v):
    if v in (None, 0, "", []):
        return None
    return max(1, min(3, int(v)))

def is_valid_chunks_per_doc(v) -> bool:
    return v is None or (type(v) is int and 1 <= v <= 3)

try:
    querit_search._invoke(query=q, chunks_per_doc=c)
except ValueError as e:
    if "chunks_per_doc" in str(e):
        c = None; querit_search._invoke(query=q, chunks_per_doc=c)
    raise

When it happens

Trigger: chunks_per_doc=0 or 4 (outside 1..3), chunks_per_doc=2.0 (float), chunks_per_doc="2" (string), or a workflow binding None-alternatives like 0 instead of omitting the field.

Common situations: Users asking for 'more chunks per document' and setting 5; UI numeric steppers emitting floats; parameter templates defaulting to 0 to mean 'unset'.

Related errors

• Querit urls must contain between 1 and 10 non-empty strings.
• Querit urls must be absolute HTTP or HTTPS URLs.
• Querit format must be text, markdown, or html.
• Querit crawl_timeout must be an integer from 1 to 60.
• Querit extras_meta must be a boolean.

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/3387d0e7e83631a9. Report an issue: GitHub.