HKUDS/Vibe-Trading · error · FutuDependencyError

futu-api is not installed; run `pip install futu-api`.

Error message

futu-api is not installed; run `pip install futu-api`.

What it means

Raised by _require_futu when the optional 'futu-api' Python package is not installed. All Futu SDK functions that need the real API gate through this check.

Source

Thrown at agent/src/trading/connectors/futu/sdk.py:977

        return f"Futu unlock_trade failed: {data}"
    return None


def _order_error(cfg: FutuConfig, message: str) -> dict[str, Any]:
    """Build a fail-closed order error envelope tagged with the profile."""
    return {"status": "error", "error": message, "profile": cfg.profile}


# ---------------------------------------------------------------------------
# SDK plumbing
# ---------------------------------------------------------------------------


def _require_futu() -> ModuleType:
    try:
        import futu  # type: ignore
    except ModuleNotFoundError as exc:
        raise FutuDependencyError("futu-api is not installed; run `pip install futu-api`.") from exc
    return futu


def tcp_port_open(host: str, port: int, timeout: float = 0.5) -> bool:
    """Return whether a TCP socket accepts connections."""
    try:
        with socket.create_connection((host, int(port)), timeout=timeout):
            return True
    except OSError:
        return False


def _assert_gateway(cfg: FutuConfig) -> None:
    """Fail with a clean error when the local OpenD gateway is unreachable."""
    if not tcp_port_open(cfg.host, cfg.port):
        raise FutuConfigError(
            f"No Futu OpenD gateway is listening at {cfg.host}:{cfg.port}. "
            "Start OpenD, log in, and confirm the API port."

View on GitHub (pinned to 80ffdda44c)

Solutions

1. pip install futu-api
2. Add futu-api to your project dependencies
3. Use futu_available() to feature-gate Futu code paths

Example fix

# before
snapshot = get_account_snapshot()  # ModuleNotFoundError wrapped
# after
if futu_available():
    snapshot = get_account_snapshot()

from src.trading.connectors.futu.sdk import futu_available
if not futu_available():
    disable_futu_features()

def futu_available() -> bool:
    try:
        import futu  # noqa: F401
        return True
    except ModuleNotFoundError:
        return False

try:
    snap = get_account_snapshot()
except FutuDependencyError:
    logger.warning('futu-api missing; skipping Futu integration')

When it happens

Trigger: Calling get_account_snapshot/get_positions/get_historical_bars etc. in an environment where `import futu` fails; futu_available() exists to probe this.

Common situations: Fresh virtualenv without the optional dependency, dependency not pinned in requirements, production image missing the extra.

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

• {alpha_id}: import failed: {exc}
• tushare not installed: {exc}
• tigeropen is not installed; run `pip install tigeropen`.
• unknown zoo {v!r}; expected one of {sorted(_VALID_ZOOS)}
• {alpha.id}: could not build import spec for {py_file}

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/29776b9df2ed063b. Report an issue: GitHub.