ZhuLinsen/daily_stock_analysis · error · FutuPortfolioError

未安装 Futu OpenAPI SDK；请先执行 `pip install "futu-api==10.8.6808"

Error message

未安装 Futu OpenAPI SDK；请先执行 `pip install "futu-api==10.8.6808"`。

What it means

FutuPortfolioError raised in src/brokers/futu/portfolio.py:67 when importing the pinned Futu OpenAPI SDK ('from futu import ...') fails with ImportError. The module deliberately imports the SDK lazily so the rest of the app runs without Futu support; this error means futu-api is missing from the environment (the project pins futu-api==10.8.6808).

Source

Thrown at src/brokers/futu/portfolio.py:67

_STATIC_INFO_BATCH_SIZE = 100


def _load_futu_api() -> _FutuApi:
    """Import the supported Futu SDK surface or raise an actionable error."""

    try:
        from futu import (
            Market,
            OpenQuoteContext,
            OpenSecTradeContext,
            RET_OK,
            SecurityFirm,
            SecurityType,
            TrdEnv,
            TrdMarket,
        )
    except ImportError as exc:
        raise FutuPortfolioError(
            "未安装 Futu OpenAPI SDK；请先执行 "
            "`pip install \"futu-api==10.8.6808\"`。"
        ) from exc
    except Exception as exc:  # noqa: BLE001 - SDK import initializes its file logger
        raise FutuPortfolioError(f"加载 Futu OpenAPI SDK 失败: {exc}") from exc

    return _FutuApi(
        OpenQuoteContext=OpenQuoteContext,
        OpenSecTradeContext=OpenSecTradeContext,
        Market=Market,
        RET_OK=RET_OK,
        SecurityFirm=SecurityFirm,
        SecurityType=SecurityType,
        TrdEnv=TrdEnv,
        TrdMarket=TrdMarket,
    )

View on GitHub (pinned to 5159bd72e8)

Solutions

1. Install the pinned SDK exactly as the message says: pip install "futu-api==10.8.6808" (keep the pin; the code's IPv4 and table handling are written against this version).
2. Verify with 'python -c "import futu; print(futu.__version__)"' in the same interpreter/venv the app runs under.
3. If Futu is intentionally unused in that deployment, avoid triggering the Futu portfolio path (do not set it as the portfolio source) so the lazy import never runs.
4. If deploying via Docker, add the pin to the image's requirements so rebuilds are reproducible.

Example fix

# before: runtime failure
from src.brokers.futu import portfolio  # later raises FutuPortfolioError

# after: explicit capability check at startup
try:
    import futu  # noqa: F401
    FUTU_AVAILABLE = True
except ImportError:
    FUTU_AVAILABLE = False

if not FUTU_AVAILABLE:
    raise SystemExit("Futu source requires: pip install 'futu-api==10.8.6808'")

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

assert futu_sdk_available(), "pip install 'futu-api==10.8.6808'"

try:
        from src.brokers.futu import portfolio
    except Exception as exc:  # module wraps import errors in FutuPortfolioError
        if '未安装 Futu OpenAPI SDK' in str(exc):
            log.warning('Futu unavailable: install futu-api==10.8.6808; skipping broker source')
        else:
            raise

When it happens

Trigger: Invoking the Futu portfolio source (e.g. fetching a Futu-sourced portfolio/positions) in an environment where 'pip install futu-api==10.8.6808' was never run; a venv/Docker image built without the optional broker extras; a CI job that installs only requirements.txt while futu-api is optional.

Common situations: Fresh clone/deploy without the broker dependency; switching virtualenvs; Docker images for the web/API tier that omit the optional SDK; dependency cleanup that removed the pin.

Related errors

• longbridge SDK is not installed. Run `pip install -r require
• 加载 Futu OpenAPI SDK 失败: {exc}
• 未找到状态为 ACTIVE 的 Futu REAL 普通或 MASTER 证券账户
• 请安装 schedule 库: pip install schedule
• invalid_import_file

AI-assisted analysis of ZhuLinsen/daily_stock_analysis@5159bd72e8 (2026-08-15). Data as JSON: /api/errors/ce5e914a44a864ec. Report an issue: GitHub.