infiniflow/ragflow · error · ValueError

Please check runtime conf, {} = {} does not match user-param

Error message

Please check runtime conf, {} = {} does not match user-parameter restriction

What it means

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.

Source

Thrown at agent/component/base.py:248

        for variable in var_list:
            attr = getattr(param_obj, variable)

            if type(attr).__name__ in self.builtin_types or attr is None:
                if variable not in validation_json:
                    continue

                validation_dict = validation_json[default_section][variable]
                value = getattr(param_obj, variable)
                value_legal = False

                for op_type in validation_dict:
                    if self.func[op_type](value, validation_dict[op_type]):
                        value_legal = True
                        break

                if not value_legal:
                    raise ValueError("Please check runtime conf, {} = {} does not match user-parameter restriction".format(variable, value))

            elif variable in validation_json:
                self._validate_param(attr, validation_json)

    @staticmethod
    def check_string(param, description):
        if type(param).__name__ not in ["str"]:
            raise ValueError(description + " {} not supported, should be string type".format(param))

    @staticmethod
    def check_empty(param, description):
        if not param:
            raise ValueError(description + " does not support empty value.")

    @staticmethod
    def check_nonnegative_integer(param, description):
        if type(param).__name__ not in ["int", "long"] or param < 0:
            raise ValueError(description + " {} not supported, should be 0 or positive integer".format(param))

View on GitHub (pinned to 554fb1133a)

Solutions

1. 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.
2. Open the component in the canvas UI — dropdowns/bounded inputs encode the restriction and will only produce legal values.
3. If the restriction is wrong/outdated, fix the param class's validation_json rather than disabling validation.
4. After upgrading components, re-validate saved runtime confs and migrate affected values.

Example fix

# before (runtime conf)
kb_id: "not-a-real-kb"   # fails restriction

# after
kb_id: "valid_kb_id"     # value accepted by validation_json

def check_restriction(value, validation_dict, ops):
    return any(ops[op](value, bound) for op, bound in validation_dict.items())

# use before run:
assert check_restriction(conf['category'], {'in': ALLOWED}, ops_table)

try:
    param.check()
except ValueError as e:
    if 'user-parameter restriction' in str(e):
        var, _, val = parse_restriction_error(str(e))
        suggest_allowed_values(var)  # drive the user back to legal values
        raise

When it happens

Trigger: 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().

Common situations: 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().

Related errors

• {component_name}: {e}
• Param define nesting too deep!!!, can not parse it
• cpn `{name}` has redundant parameters: `{[redundant_attrs]}`
• {} not supported, should be string type
• does not support empty value.

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