microsoft/autogen · error · TypeError

Cannot dump component with local class

Error message

Cannot dump component with local class

What it means

dump_component derives the provider string from the class's import path via _type_to_provider_str. If the class was defined inside a function (module path contains '<locals>'), the provider cannot round-trip: no import statement can reach it. dump_component raises TypeError('Cannot dump component with local class'). component_provider_override does not help — the check runs after it, but the override is only used if set; the guard applies to the derived provider.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_component_config.py:166

        Raises:
            TypeError: If the component is a local class.

        Returns:
            ComponentModel: The model representing the component.
        """
        if self.component_provider_override is not None:
            provider = self.component_provider_override
        else:
            provider = _type_to_provider_str(self.__class__)
            # Warn if internal module name is used,
            if "._" in provider:
                warnings.warn(
                    "Internal module name used in provider string. This is not recommended and may cause issues in the future. Silence this warning by setting component_provider_override to this value.",
                    stacklevel=2,
                )

        if "<locals>" in provider:
            raise TypeError("Cannot dump component with local class")

        if not hasattr(self, "component_type"):
            raise AttributeError("component_type not defined")

        description = self.component_description
        if description is None and self.__class__.__doc__:
            # use docstring as description
            docstring = self.__class__.__doc__.strip()
            for marker in ["\n\nArgs:", "\n\nParameters:", "\n\nAttributes:", "\n\n"]:
                docstring = docstring.split(marker)[0]
            description = docstring.strip()

        obj_config = self._to_config().model_dump(exclude_none=True)
        model = ComponentModel(
            provider=provider,
            component_type=self.component_type,
            version=self.component_version,
            component_version=self.component_version,

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Move the class to module top level so its provider becomes an importable 'package.module.Class'.
2. Set component_provider_override to an importable class path if the class must stay nested but is identical to an importable one.
3. Do not call dump_component on test-local/notebook-local classes; construct their configs directly.

Example fix

# before
def make_component():
    class LocalComponent(ComponentToConfig): ...
    return LocalComponent().dump_component()  # TypeError

# after
# module scope: my_package/components.py
class LocalComponent(ComponentToConfig): ...

# usage
LocalComponent().dump_component()  # provider 'my_package.components.LocalComponent'

provider = f"{type(comp).__module__}.{type(comp).__qualname__}"
if "<locals>" in provider:
    raise TypeError(f"cannot dump locally-defined class {type(comp).__qualname__}; move it to module scope")

def is_module_level_class(cls: type) -> bool:
    return "<locals>" not in cls.__qualname__

try:
    model = comp.dump_component()
except TypeError as e:
    if "local class" in str(e):
        # reconstruct config manually for this nested class
        raise
    raise

When it happens

Trigger: Defining a component class inside a function, pytest test body, or notebook cell scope, then calling dump_component(); dynamically created classes via type(...) inside a helper.

Common situations: Notebook prototypes declaring component classes inline; test-local components accidentally serialized; factory functions that create classes per call.

Related errors

• component_type not defined
• This component does not support dumping to config
• This component does not support loading from past versions
• Invalid
• Invalid agent type: {type}. Allowed values MUST match the re

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/a4f9832e8f8f931a. Report an issue: GitHub.