agentscope-ai/agentscope · error · ImportError

Feishu channel requires 'lark-oapi' (pip install lark-oapi).

Error message

Feishu channel requires 'lark-oapi' (pip install lark-oapi).

What it means

ImportError raised inside _launch_ws_thread when starting the Feishu (Lark) channel's WebSocket listener: the optional dependency lark-oapi is not installed. The Feishu channel is an optional extra, so the SDK only imports lark_oapi lazily at listen time and converts the missing module into an actionable ImportError with the pip install hint.

Source

Thrown at src/agentscope/app/channel/_feishu/_channel.py:283

                    ws_loop.call_soon_threadsafe(ws_loop.stop)
                except RuntimeError:
                    pass  # loop already closed
            if self._ws_thread and self._ws_thread.is_alive():
                self._ws_thread.join(timeout=5.0)
            if self._http:
                await self._http.aclose()
                self._http = None

    def _launch_ws_thread(self) -> threading.Thread:
        """Start the lark WS client on a daemon thread with its own loop.

        Returns:
            `threading.Thread`: The started WS thread (daemon).
        """
        try:
            import lark_oapi as lark
        except ImportError as e:
            raise ImportError(
                "Feishu channel requires 'lark-oapi' "
                "(pip install lark-oapi).",
            ) from e

        loop = self._loop
        assert loop is not None  # set in start_listening before this runs

        def on_message(data: "P2ImMessageReceiveV1") -> None:
            """Bridge an inbound message onto the app loop.

            Args:
                data (`P2ImMessageReceiveV1`): The SDK message event.
            """
            asyncio.run_coroutine_threadsafe(self._on_message(data), loop)

        def on_card_action(
            data: "P2CardActionTrigger",
        ) -> "P2CardActionTriggerResponse":

View on GitHub (pinned to e90f1c7592)

Solutions

1. pip install lark-oapi (or install agentscope with the feishu extra, e.g. pip install 'agentscope[feishu]')
2. Add lark-oapi to your project's requirements/pyproject dependencies if you ship Feishu support
3. Verify with python -c "import lark_oapi" before starting the app
4. If Feishu is not needed, remove the Feishu channel from create_app(channels=[...]) so the listener never starts

Example fix

# before
pip install agentscope
app = create_app(channels=[FeishuChannel])

# after
pip install lark-oapi
app = create_app(channels=[FeishuChannel])

try:
    import lark_oapi  # noqa: F401
    FEISHU_AVAILABLE = True
except ImportError:
    FEISHU_AVAILABLE = False

if using_feishu and not FEISHU_AVAILABLE:
    raise SystemExit("Install with: pip install lark-oapi")

try:
    channel.start_listening()
except ImportError as e:
    if "lark-oapi" in str(e):
        subprocess.check_call([sys.executable, "-m", "pip", "install", "lark-oapi"])
        channel.start_listening()

When it happens

Trigger: Calling start_listening() on a Feishu channel (or create_app with a Feishu channel that starts listening) in an environment where lark-oapi is not installed — e.g. agentscope installed without the feishu extra, a slim Docker image, or a fresh virtualenv.

Common situations: Installing the base package without extras (pip install agentscope vs agentscope[feishu]), CI environments with a trimmed dependency set, dependency pruning tools removing 'unused' optional deps.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• "ReMeMiddleware requires the `reme-ai` package. Install it w
• CosyVoice TTS synthesis timed out after 30s
• CosyVoice TTS synthesis failed: no audio after {self.max_ret
• TTS model is not connected. Call `connect()` first.
• TTS synthesis failed: no audio after {self.max_retries} atte

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