agentscope-ai/agentscope · error · ValueError

Unknown permission mode: {mode}

Error message

Unknown permission mode: {mode}

What it means

The permission engine dispatched on PermissionMode but found a value matching none of ACCEPT_EDITS, BYPASS, DONT_ASK (or DEFAULT handled earlier). This indicates an unknown/invalid permission mode string reached check_permission.

Source

Thrown at src/agentscope/permission/_engine.py:115

                The tool input data, used for rule matching and
                tool-specific checks.

        Returns:
            `PermissionDecision`:
                Decision indicating whether to allow, deny, or ask.
        """
        mode = self.context.mode
        if mode == PermissionMode.DEFAULT:
            return await self._check_default(tool, tool_input)
        if mode == PermissionMode.EXPLORE:
            return await self._check_explore(tool, tool_input)
        if mode == PermissionMode.ACCEPT_EDITS:
            return await self._check_accept_edits(tool, tool_input)
        if mode == PermissionMode.BYPASS:
            return await self._check_bypass(tool, tool_input)
        if mode == PermissionMode.DONT_ASK:
            return await self._check_dont_ask(tool, tool_input)
        raise ValueError(f"Unknown permission mode: {mode}")

    async def _check_default(
        self,
        tool: ToolBase,
        tool_input: dict[str, Any],
    ) -> PermissionDecision:
        """Permission check for :attr:`PermissionMode.DEFAULT`.

        Every operation requires explicit permission unless it is a
        read-only invocation, an allow rule matches, or the tool's own
        ``check_permissions`` returns ALLOW. Evaluation order:

        1. Deny rules → DENY
        2. Ask rules → ASK (with suggestions)
        3. Read-only fast path → ALLOW
        4. ``tool.check_permissions``:
            - ALLOW / DENY → returned as-is
            - Safety ASK (bypass-immune) → returned with suggestions; cannot

View on GitHub (pinned to e90f1c7592)

Solutions

1. Use one of the documented PermissionMode values, ideally the enum: PermissionMode.DEFAULT / ACCEPT_EDITS / BYPASS / DONT_ASK
2. Check the exact spelling/casing expected by your agentscope version (see PermissionMode enum source)
3. Validate config values against PermissionMode at load time

Example fix

# before
agent = ReActAgent(..., permission={'mode': 'accept_edit'})

# after
from agentscope.permission import PermissionMode
agent = ReActAgent(..., permission={'mode': PermissionMode.ACCEPT_EDITS})

from agentscope.permission import PermissionMode
assert mode in PermissionMode, f'unknown permission mode: {mode}'

from agentscope.permission import PermissionMode

def is_permission_mode(m) -> bool:
    return m in PermissionMode

When it happens

Trigger: Setting agent permission mode to a typo like 'accept_edit', 'auto', 'always', or passing a raw string not in the PermissionMode enum.

Common situations: Passing mode from a CLI/config with the wrong name; version change renaming modes; constructing PermissionConfig manually with arbitrary strings.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The injection template must contain the '{runtime_state}' pl
• "AgentScopeLLM requires `model` in the config to be an Agent
• f"AgentScopeLLM `model` must be a ChatModelBase, got {type(s
• "AgentScopeEmbedding requires `model` in the config to be an
• "build_mem0_config requires `chat_model` and `embedding_mode

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