deepset-ai/haystack · error · ComponentError

'output_types' decorator can only be used on 'run' and 'run_

Error message

'output_types' decorator can only be used on 'run' and 'run_async' methods

What it means

The @component.output_types decorator declares a component's output sockets and may only decorate the component's entrypoint methods. Haystack raises this ComponentError during decoration when the decorated method is anything other than 'run' or 'run_async', because output types can only be attached to those methods (ComponentMeta later reads the cached sockets from them).

Source

Thrown at haystack/core/component/component.py:552

        class MyComponent:
            @component.output_types(output_1=int, output_2=str)
            def run(self, value: int):
                return {"output_1": 1, "output_2": "2"}
        ```
        """

        def output_types_decorator(run_method: Callable[RunParamsT, RunReturnT]) -> Callable[RunParamsT, RunReturnT]:
            """
            Decorator that sets the output types of the decorated method.

            This happens at class creation time, and since we don't have the decorated
            class available here, we temporarily store the output types as an attribute of
            the decorated method. The ComponentMeta metaclass will use this data to create
            sockets at instance creation time.
            """
            method_name = run_method.__name__
            if method_name not in ("run", "run_async"):
                raise ComponentError("'output_types' decorator can only be used on 'run' and 'run_async' methods")

            setattr(  # noqa: B010
                run_method,
                "_output_types_cache",
                {name: OutputSocket(name=name, type=type_) for name, type_ in types.items()},
            )
            return run_method

        return output_types_decorator

    def _component(self, cls: type[T]) -> type[T]:
        """
        Decorator validating the structure of the component and registering it in the components registry.
        """
        logger.debug("Registering {component} as a component", component=cls)

        # Check for required methods and fail as soon as possible
        if not hasattr(cls, "run"):

View on GitHub (pinned to e318778c9b)

Solutions

1. Move the @component.output_types decorator so it directly wraps the 'run' (or 'run_async') method
2. If outputs differ for async, decorate both 'run' and 'run_async' separately with @component.output_types
3. Remove the decorator from non-entrypoint helper methods and return a dataclass/dict typed via run's decorator instead

Example fix

// before
class MyComponent:
    @component.output_types(str)
    def prepare(self, x: int) -> str: ...

    def run(self, x: int) -> dict[str, str]: ...

// after
class MyComponent:
    def prepare(self, x: int) -> str: ...

    @component.output_types(str)
    def run(self, x: int) -> dict[str, str]: ...

def ensure_output_types_on_run(cls) -> None:
    for name, member in vars(cls).items():
        if hasattr(member, "_output_types_cache") and name not in ("run", "run_async"):
            raise TypeError(f"@output_types is on '{name}'; only 'run'/'run_async' are allowed")

def is_runlike(obj) -> bool:
    return callable(obj) and getattr(obj, "__name__", None) in ("run", "run_async")

try:
    component.output_types(str)(my_func)
except ComponentError as e:
    logging.error("output_types applied to non-run method: %s", e)

When it happens

Trigger: Applying @component.output_types(SomeType) to any method other than run or run_async — e.g. a helper method, a __init__, a custom named method, or applying it at module level to a plain function.

Common situations: Refactoring a component and accidentally decorating a private helper; typos like @output_types on 'run_sync'; copy-pasting the decorator onto a callback; trying to declare outputs for multiple methods.

Related errors

• {cls.__name__} must have a 'run()' method. See the docs for
• Parameters of 'run' and 'run_async' methods must be the same
• Method 'run_async' of component '{cls.__name__}' must be a c
• Cannot set input types on a component that doesn't have a kw
• Cannot call `set_output_types` on a component that already h

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/eef1c2d6f47985bf. Report an issue: GitHub.