{"record":{"id":"a1361f2117d07c32","repo":"infiniflow/ragflow","slug":"please-check-runtime-conf-does-not-match","errorCode":null,"errorMessage":"Please check runtime conf, {} = {} does not match user-parameter restriction","messagePattern":"Please check runtime conf, (.+?) = (.+?) does not match user-parameter restriction","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"agent/component/base.py","lineNumber":248,"sourceCode":"\n        for variable in var_list:\n            attr = getattr(param_obj, variable)\n\n            if type(attr).__name__ in self.builtin_types or attr is None:\n                if variable not in validation_json:\n                    continue\n\n                validation_dict = validation_json[default_section][variable]\n                value = getattr(param_obj, variable)\n                value_legal = False\n\n                for op_type in validation_dict:\n                    if self.func[op_type](value, validation_dict[op_type]):\n                        value_legal = True\n                        break\n\n                if not value_legal:\n                    raise ValueError(\"Please check runtime conf, {} = {} does not match user-parameter restriction\".format(variable, value))\n\n            elif variable in validation_json:\n                self._validate_param(attr, validation_json)\n\n    @staticmethod\n    def check_string(param, description):\n        if type(param).__name__ not in [\"str\"]:\n            raise ValueError(description + \" {} not supported, should be string type\".format(param))\n\n    @staticmethod\n    def check_empty(param, description):\n        if not param:\n            raise ValueError(description + \" does not support empty value.\")\n\n    @staticmethod\n    def check_nonnegative_integer(param, description):\n        if type(param).__name__ not in [\"int\", \"long\"] or param < 0:\n            raise ValueError(description + \" {} not supported, should be 0 or positive integer\".format(param))","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/component/base.py#L230-L266","documentation":"Component params can declare user-parameter restrictions (an operator/value validation table, checked via self.func[op_type]). After recursively applying config, each restricted variable's value is tested against every operator; if none passes, this ValueError reports the variable and its rejected value.","triggerScenarios":"A param class defines validation_json restrictions (e.g. value in a set, range via operators) and the runtime conf sets the variable to a value outside all allowed operators — agent/component/base.py:248 during check().","commonSituations":"Setting an enum-like param to a value not in the allowed list; hand-editing runtime conf YAML/JSON with values the UI's dropdown would never produce; component version added new restrictions so old confs now fail check().","solutions":["Read the message for the variable name and value, then set it to one of the allowed values defined in the component's validation spec.","Open the component in the canvas UI — dropdowns/bounded inputs encode the restriction and will only produce legal values.","If the restriction is wrong/outdated, fix the param class's validation_json rather than disabling validation.","After upgrading components, re-validate saved runtime confs and migrate affected values."],"exampleFix":"# before (runtime conf)\nkb_id: \"not-a-real-kb\"   # fails restriction\n\n# after\nkb_id: \"valid_kb_id\"     # value accepted by validation_json","handlingStrategy":"validation","validationCode":"def check_restriction(value, validation_dict, ops):\n    return any(ops[op](value, bound) for op, bound in validation_dict.items())\n\n# use before run:\nassert check_restriction(conf['category'], {'in': ALLOWED}, ops_table)","typeGuard":null,"tryCatchPattern":"try:\n    param.check()\nexcept ValueError as e:\n    if 'user-parameter restriction' in str(e):\n        var, _, val = parse_restriction_error(str(e))\n        suggest_allowed_values(var)  # drive the user back to legal values\n        raise","preventionTips":["Read restriction specs from the component when building forms so only legal values are offered.","Never hand-edit restricted fields in raw runtime conf.","Re-validate saved confs after component upgrades that change restrictions."],"tags":["canvas","parameter-validation","runtime-conf","restrictions"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}