agentscope-ai/agentscope · error · ValueError

Missing '{channel_cls.platform_bot_id_field}' in credentials

Error message

Missing '{channel_cls.platform_bot_id_field}' in credentials.

What it means

ValueError raised by ChannelRegistry.extract_platform_bot_id when the channel class is registered and has a platform_bot_id_field, but the provided credentials dict lacks that key or its value is empty/falsy. It means the stored/sent credentials are incomplete for identifying the bot on the platform.

Source

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

    def extract_platform_bot_id(
        self,
        channel_type: str,
        credentials: dict,
    ) -> str:
        """Read the bot-identifying credential field, for uniqueness.

        Args:
            channel_type (`str`): The platform type id.
            credentials (`dict`): Raw credentials to read the bot id from.
        """
        channel_cls = self._classes.get(channel_type)
        if channel_cls is None or not channel_cls.platform_bot_id_field:
            raise ValueError(
                f"Cannot extract platform_bot_id for type '{channel_type}'.",
            )
        bot_id = credentials.get(channel_cls.platform_bot_id_field)
        if not bot_id:
            raise ValueError(
                f"Missing '{channel_cls.platform_bot_id_field}' in "
                f"credentials.",
            )
        return str(bot_id)

View on GitHub (pinned to e90f1c7592)

Solutions

1. Include the exact key named by the channel's platform_bot_id_field with a non-empty value in the credentials dict
2. Check the env/secret source actually populates that key (no empty defaults)
3. Validate credentials client-side against the channel class before sending (see defense section)

Example fix

# before
credentials = {"app_secret": "xxx"}  # bot id key missing
registry.extract_platform_bot_id("feishu", credentials)

# after
credentials = {"app_secret": "xxx", "app_id": "cli_a1b2c3"}
registry.extract_platform_bot_id("feishu", credentials)

field = registry.get(channel_type).platform_bot_id_field
if not credentials.get(field):
    raise ValueError(f"credentials must include non-empty {field!r}")

def credentials_complete(registry, channel_type: str, credentials: dict) -> bool:
    cls = registry.get(channel_type)
    if cls is None:
        return False
    return bool(credentials.get(cls.platform_bot_id_field))

try:
    bot_id = registry.extract_platform_bot_id(t, creds)
except ValueError as e:
    if "Missing" in str(e) and "in credentials" in str(e):
        return HTTPException(422, detail=str(e))  # surface to API client

When it happens

Trigger: Creating or updating a channel via the API (create/update/delete -> extract_platform_bot_id) with a credentials payload missing the key named by platform_bot_id_field — e.g. sending {"app_secret": ...} for Feishu without "app_id"/bot id, or passing an empty string value.

Common situations: Partial credentials pasted from the platform console, env var for the bot id unset so it defaults to "", mismatch between the field name your code sends and the class's platform_bot_id_field (e.g. "bot_id" vs "botId").

Related errors

• Cannot extract platform_bot_id for type '{channel_type}'.
• {channel_cls.__name__} must set a non-empty 'channel_type' t
• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• The 'reserve_ratio' of the context config must be smaller th
• The 'context_buffer_ratio' of the injection config must be s

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