agentscope-ai/agentscope · error · ValueError

{channel_cls.__name__} must set a non-empty 'channel_type' t

Error message

{channel_cls.__name__} must set a non-empty 'channel_type' to be registered.

What it means

ValueError raised by ChannelRegistry.register when a ChannelBase subclass has an empty/None channel_type class attribute. The registry keys channel classes by channel_type, so a blank type would make the channel unreachable (or silently collide with other empty keys); registration therefore fails fast at app creation time.

Source

Thrown at src/agentscope/app/channel/_registry.py:68

                ``create_app(channels=[...])``.
        """
        self._classes: dict[str, type["ChannelBase"]] = {}
        for channel_cls in channels or []:
            self.register(channel_cls)

    def __bool__(self) -> bool:
        """Whether any channel type is registered (feature enabled)."""
        return bool(self._classes)

    def register(self, channel_cls: type["ChannelBase"]) -> None:
        """Register a channel class under its ``channel_type``.

        Args:
            channel_cls (`type[ChannelBase]`): The channel class to add.
        """
        channel_type = channel_cls.channel_type
        if not channel_type:
            raise ValueError(
                f"{channel_cls.__name__} must set a non-empty "
                f"'channel_type' to be registered.",
            )
        self._classes[channel_type] = channel_cls

    def get(self, channel_type: str) -> type["ChannelBase"] | None:
        """Return the channel class for a type, or ``None``.

        Args:
            channel_type (`str`): The platform type id.
        """
        return self._classes.get(channel_type)

    def has_type(self, channel_type: str) -> bool:
        """Whether a type is registered.

        Args:
            channel_type (`str`): The platform type id.

View on GitHub (pinned to e90f1c7592)

Solutions

1. Add a unique non-empty channel_type class attribute to your channel subclass (e.g. channel_type = "mychat")
2. Check you didn't shadow channel_type with an instance attribute or a None default
3. Ensure any base-class default is not being set to empty string in intermediate subclasses

Example fix

# before
class MyChannel(ChannelBase):
    # channel_type missing
    ...

# after
class MyChannel(ChannelBase):
    channel_type = "mychat"
    ...

def is_registerable_channel(cls) -> bool:
    return isinstance(cls, type) and issubclass(cls, ChannelBase) and bool(getattr(cls, "channel_type", None))

def assert_valid_channel(cls: type[ChannelBase]) -> None:
    if not getattr(cls, "channel_type", None):
        raise TypeError(f"{cls.__name__} must define a non-empty channel_type")

try:
    app = create_app(channels=[MyChannel])
except ValueError as e:
    if "channel_type" in str(e):
        fix_and_define_channel_type()  # add class attribute and recreate app

When it happens

Trigger: Calling create_app(channels=[MyChannel]) where MyChannel subclasses ChannelBase but does not define channel_type (or sets it to "" or None). The registry's __init__ registers each provided class, so the error surfaces during create_app.

Common situations: Writing a custom channel and forgetting the channel_type attribute, overriding class attributes in __init_subclass__ and blanking channel_type, copy-pasting a channel stub without filling in required class fields.

Related errors

• Channel type '{channel_type}' is not registered; pass it to
• Cannot extract platform_bot_id for type '{channel_type}'.
• Missing '{channel_cls.platform_bot_id_field}' in credentials
• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• The 'reserve_ratio' of the context config must be smaller th

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/00c3d83d6ba572ed. Report an issue: GitHub.