infiniflow/ragflow · error · ValueError

101

101

Error message

top_k must be integer and score_threshold must be numeric

What it means

Raised while normalizing GET query parameters for the Dify-compatible retrieval endpoint: top_k could not be int()-converted or score_threshold could not be float()-converted. Empty/absent values are skipped, so this fires only when a non-empty non-numeric value is supplied.

Source

Thrown at api/apps/restful_apis/dify_retrieval_api.py:61

        method = request.method
    except RuntimeError:
        # Unit tests may call the handler directly without a request context.
        method = "POST"
    if method == "GET":
        query_args = request.args
        retrieval_setting = {}
        knowledge_id = query_args.get("knowledge_id")
        query = query_args.get("query")
        use_kg = str(query_args.get("use_kg", "")).lower() in {"1", "true", "yes", "on"}
        top_k = query_args.get("top_k")
        score_threshold = query_args.get("score_threshold")
        try:
            if top_k not in (None, ""):
                retrieval_setting["top_k"] = int(top_k)
            if score_threshold not in (None, ""):
                retrieval_setting["score_threshold"] = float(score_threshold)
        except (TypeError, ValueError):
            raise ValueError("top_k must be integer and score_threshold must be numeric")
        safe_query = f"len={len(query)}" if isinstance(query, str) else "len=0"
        logger.debug(
            "Dify retrieval GET normalization: knowledge_id=%s query=%s use_kg=%s top_k=%s score_threshold=%s",
            knowledge_id,
            safe_query,
            use_kg,
            retrieval_setting.get("top_k"),
            retrieval_setting.get("score_threshold"),
        )

        req = {
            "knowledge_id": knowledge_id,
            "query": query,
            "use_kg": use_kg,
            "retrieval_setting": retrieval_setting,
        }
        return req
    req = await get_request_json()

View on GitHub (pinned to 554fb1133a)

Solutions

1. Send top_k as an integer literal (e.g. top_k=1024) and score_threshold as a decimal number (e.g. score_threshold=0.2).
2. Strip any % sign or unit and convert in the client before building the query string.
3. Omit the parameters entirely to use server defaults rather than sending placeholders.

Example fix

# before
GET /api/v1/dify/retrieval?...&top_k=10.5&score_threshold=0.2
# after
GET /api/v1/dify/retrieval?...&top_k=10&score_threshold=0.2

def normalize_get_params(query_args):
    top_k = query_args.get("top_k")
    score = query_args.get("score_threshold")
    if top_k not in (None, ""):
        top_k = int(str(top_k).strip())
    if score not in (None, ""):
        score = float(str(score).strip().rstrip("%"))
    return top_k, score

const isIntParam = (v: unknown): v is number | string =>
  typeof v === "number" && Number.isInteger(v) || /^-?\d+$/.test(String(v).trim());

try:
    r = requests.get(url, params=p)
except requests.HTTPError as e:
    if "top_k must be integer" in e.response.text:
        p["top_k"], p["score_threshold"] = int(p["top_k"]), float(p["score_threshold"])
        r = requests.get(url, params=p)
    else:
        raise

When it happens

Trigger: GET /api/v1/dify/retrieval?dataset_id=...&query=...&top_k=abc or score_threshold=high; also top_k=10.5 (int('10.5') raises ValueError) — note a decimal top_k triggers it too.

Common situations: Dify or custom clients sending thresholds as percentages ("85%"), localized decimals, or passing top_k with a fractional value; copy-pasting parameter examples with placeholder text.

Related errors

• dataset_id (or kb_id/knowledge_id) is required for retrieval
• Invalid {label} format: {value!r}
• main() must be defined or exported.
• main() must return a value. Use null for an empty result.
• main() returned a non-JSON-serializable value.

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