infiniflow/ragflow · error · KeyError

Miss parameter: {key}

Error message

Miss parameter: {key}

What it means

KeyError raised during chat prompt preparation when a prompt_config parameter entry is non-optional and its key is absent from kwargs. Only 'knowledge' is special-cased (auto-appended when kb_ids set); every other declared non-optional parameter must be supplied by the caller.

Source

Thrown at api/db/services/dialog_service.py:700

            yield ans
            return
        else:
            logging.debug("SQL failed or returned no results, falling back to vector search")

    param_keys = [p["key"] for p in prompt_config.get("parameters", [])]
    if dialog.kb_ids and "knowledge" not in param_keys and "{knowledge}" in prompt_config.get("system", ""):
        logging.warning("prompt_config['parameters'] is missing 'knowledge' entry despite kb_ids being set; auto-fixing.")
        prompt_config.setdefault("parameters", []).append({"key": "knowledge", "optional": False})
        param_keys.append("knowledge")
    logging.debug(f"scoped_doc_ids={scoped_doc_ids}, param_keys={param_keys}, embd_mdl={embd_mdl}")

    sys_date = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
    kwargs["date"] = sys_date
    for p in prompt_config.get("parameters", []):
        if p["key"] == "knowledge":
            continue
        if p["key"] not in kwargs and not p["optional"]:
            raise KeyError("Miss parameter: " + p["key"])
        if p["key"] not in kwargs:
            prompt_config["system"] = prompt_config["system"].replace("{%s}" % p["key"], " ")

    if len(questions) > 1 and prompt_config.get("refine_multiturn"):
        questions = [await full_question(dialog.tenant_id, dialog.llm_id, messages)]
    else:
        questions = questions[-1:]

    if prompt_config.get("cross_languages"):
        questions = [await cross_languages(dialog.tenant_id, dialog.llm_id, questions[0], prompt_config["cross_languages"])]

    if prompt_config.get("keyword", False):
        questions[-1] = questions[-1] + "," + await keyword_extraction(chat_mdl, questions[-1])
    refine_question_ts = timer()

    thought = ""
    kbinfos = {"total": 0, "chunks": [], "doc_aggs": []}
    knowledges = []

View on GitHub (pinned to 554fb1133a)

Solutions

1. Pass the missing variable in the request kwargs matching the parameter key.
2. Mark the parameter as {'optional': true} in the dialog's prompt configuration if it is genuinely optional.
3. Remove the unused {placeholder} from the system prompt and the parameters list.

Example fix

# before: prompt declares {user_name} required, request omits it
# after
resp = ask(chat_id, msg, {'user_name': 'Alice'})
# or in dialog config: {'key': 'user_name', 'optional': True}

params = dialog['prompt_config'].get('parameters', [])
missing = [p['key'] for p in params if p['key'] != 'knowledge' and not p.get('optional') and p['key'] not in kwargs]
if missing:
    raise ValueError(f'missing required prompt variables: {missing}')

try:
    chat(dialog, messages, **vars)
except KeyError as e:
    var = str(e).strip("'").replace('Miss parameter: ', '')
    vars[var] = ask_user_for(var)  # or mark optional in dialog config
    chat(dialog, messages, **vars)

When it happens

Trigger: Calling the chat flow with a dialog whose prompt template declares e.g. {'key': 'user_name', 'optional': false} in prompt_config['parameters'] but the request supplies no user_name variable.

Common situations: Editing a chat assistant's system prompt and adding a new {placeholder} marked required without updating the calling code/UI to send it; importing dialog configurations that declare parameters the caller never populates.

Related errors

• Cannot search across datasets where some have embedding mode
• Datasets use different embedding models: {[kb.embd_id for kb
• 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/07cdf847c47024f7. Report an issue: GitHub.