agentscope-ai/agentscope · error · ValueError

Channel type '{channel_type}' is not registered; pass it to

Error message

Channel type '{channel_type}' is not registered; pass it to create_app(channels=[...]).

What it means

ValueError raised by ChannelRegistry.create_channel when asked to instantiate a channel whose channel_type string was never registered. Channels must be passed to create_app(channels=[...]) so the registry knows the class; creation by type id only works for registered classes.

Source

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

        channel_id: str,
        credentials: dict,
        config: dict,
    ) -> "ChannelBase":
        """Validate stored credentials/config against the class's nested
        models and build the channel instance.

        Args:
            channel_type (`str`): The platform type id.
            channel_id (`str`): The instance's unique id.
            credentials (`dict`): Raw credentials to validate.
            config (`dict`): Raw platform options to validate.

        Raises:
            `ValueError`: If ``channel_type`` is not registered.
        """
        channel_cls = self._classes.get(channel_type)
        if channel_cls is None:
            raise ValueError(
                f"Channel type '{channel_type}' is not registered; pass it "
                f"to create_app(channels=[...]).",
            )
        return channel_cls(
            channel_id,
            channel_cls.Credentials(**credentials),
            channel_cls.Config(**config),
        )

    def schema_of(
        self,
        channel_cls: type["ChannelBase"],
    ) -> ChannelTypeSchema:
        """Build the frontend schema for one channel class.

        Args:
            channel_cls (`type[ChannelBase]`): The channel class.
        """

View on GitHub (pinned to e90f1c7592)

Solutions

1. Pass the channel class to create_app: create_app(channels=[TelegramChannel, ...]) before creating channels of that type
2. Verify the exact spelling of channel_type (it's the class attribute, not necessarily the class name)
3. If it's a custom channel, ensure its module is imported so registration happens
4. Log registry._classes keys (or expose a list endpoint) to see which types are actually available

Example fix

# before
app = create_app(...)  # no channels
ch = registry.create_channel("feishu", ...)

# after
from agentscope.app.channel import FeishuChannel
app = create_app(channels=[FeishuChannel], ...)
ch = registry.create_channel("feishu", ...)

registry = app.state.channel_registry
if registry.get("telegram") is None:
    raise RuntimeError("telegram not registered; recreate app with channels=[TelegramChannel]")

def channel_available(registry, channel_type: str) -> bool:
    return registry.get(channel_type) is not None

try:
    ch = registry.create_channel(channel_type, ...)
except ValueError as e:
    if "not registered" in str(e):
        return HTTPException(404, f"unknown channel type {channel_type}")

When it happens

Trigger: Calling registry.create_channel("telegram", ...) (or an endpoint such as channel create/_start hitting it) when the Telegram channel class was not included in create_app(channels=[...]). Also typos in the channel_type string, or referencing a builtin channel whose class was never imported/registered.

Common situations: Adding a new channel type at runtime via the API without registering its class first, forgetting to list a channel in create_app, renaming a channel_type without updating stored configs, case/typo mismatches in the type string.

Related errors

• {channel_cls.__name__} must set a non-empty 'channel_type' t
• Cannot extract platform_bot_id for type '{channel_type}'.
• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• factory must be a callable, got {type(factory).__name__}
• 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/756b9fd2ff6533b3. Report an issue: GitHub.