What causes "{component_name}: {e}" in infiniflow/ragflow?

The prefix before the colon is the component's display name — open that node in the canvas editor and fix the parameter named in the trailing message.

infiniflow/ragflow · error · ValueError

{component_name}: {e}

Error message

{component_name}: {e}

What it means

During canvas (agent workflow) construction, every component's parameters are instantiated and their check() method runs. Any exception from a component's parameter validation is re-raised as ValueError prefixed with the human-readable component name from the DSL graph, so the user knows which node failed.

Source

Thrown at agent/canvas.py:122

        for cpn in self.components.values():
            cpn["obj"]["params"]["custom_header"] = self.custom_header

        component_params = self.validate_component_parameters(self.dsl)
        for k, cpn in self.components.items():
            cpn["obj"] = component_class(cpn["obj"]["component_name"])(self, k, component_params[k])

        self.path = self.dsl["path"]

    @staticmethod
    def validate_component_parameters(dsl):
        component_params = {}
        for k, cpn in dsl["components"].items():
            param = component_class(cpn["obj"]["component_name"] + "Param")()
            param.update(cpn["obj"]["params"])
            try:
                param.check()
            except Exception as e:
                raise ValueError(Graph._get_component_name(dsl, k) + f": {e}")
            component_params[k] = param
        return component_params

    def __str__(self):
        self.dsl["path"] = self.path
        self.dsl["task_id"] = self.task_id
        dsl = {"components": {}}
        for k in self.dsl.keys():
            if k in ["components"]:
                continue
            try:
                dsl[k] = deepcopy(self.dsl[k])
            except Exception as e:
                logging.warning("Graph.__str__: deepcopy failed for dsl key '%s' (type=%s): %s. Using shallow reference.", k, type(self.dsl[k]).__name__, e)
                dsl[k] = self.dsl[k]

        for k, cpn in self.components.items():
            if k not in dsl["components"]:

View on GitHub (pinned to 554fb1133a)

Solutions

The prefix before the colon is the component's display name — open that node in the canvas editor and fix the parameter named in the trailing message.
If the DSL is generated code, validate each component's params with a dry-run param.check() before saving.
Re-export the workflow from a known-good instance if it was hand-edited beyond repair.
After upgrading, re-open and re-save old canvases in the UI so components re-serialize with current param shapes.

Example fix

# before (dsl params)
{"component_name": "Generation", "params": {"llm_id": "", "temperature": 5}}

# after
{"component_name": "Generation", "params": {"llm_id": "my_llm@openai", "temperature": 0.7}}

Defensive patterns

Strategy: try-catch

Validate before calling

def lint_canvas(dsl):
    from agent.canvas import Canvas
    try:
        Canvas.validate_component_parameters(dsl)
        return True
    except ValueError as e:
        print(f'invalid canvas: {e}')
        return False

Try / catch

try:
    graph = Graph(dsl)
except ValueError as e:
    # message is '<component name>: <inner validation error>'
    comp, _, detail = str(e).partition(': ')
    report_to_user(comp, detail)
    raise

Prevention

Validate the DSL with validate_component_parameters before persisting or running it.
Use the canvas UI rather than hand-editing JSON for parameter changes.
Re-open and re-save old workflows after component upgrades.

When it happens

Trigger: Building a Graph/Canvas from a DSL whose component params fail param.check() — e.g. an LLM component with empty model name, a retrieval component with bad top_n, or any of the check_* validators in agent/component/base.py failing for that component's params.

Common situations: Hand-edited or programmatically generated workflow JSON with invalid parameter values; templates authored against an older component API; importing a canvas exported from another instance with different component versions; frontend allowing invalid values into saved params.

Related errors

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