What causes "MCP task service not available" in bytedance/deer-flow?

Resolve the underlying init failure shown in Gateway startup logs (persistence/migrations first)

bytedance/deer-flow · error · HTTPException

MCP task service not available

Error message

MCP task service not available

What it means

HTTP 503 from get_mcp_task_service() when app.state.mcp_task_service is None. The MCP task service coordinates task lifecycle operations on top of mcp_task_repo; missing means MCP task subsystem bootstrap did not complete.

Source

Thrown at backend/app/gateway/deps.py:675

def get_scheduled_task_service(request: Request):
    val = getattr(request.app.state, "scheduled_task_service", None)
    if val is None:
        raise HTTPException(status_code=503, detail="Scheduled task service not available")
    return val


def get_mcp_task_repo(request: Request):
    val = getattr(request.app.state, "mcp_task_repo", None)
    if val is None:
        raise HTTPException(status_code=503, detail="MCP task repo not available")
    return val


def get_mcp_task_service(request: Request):
    val = getattr(request.app.state, "mcp_task_service", None)
    if val is None:
        raise HTTPException(status_code=503, detail="MCP task service not available")
    return val


def get_run_context(request: Request) -> RunContext:
    """Build a :class:`RunContext` from ``app.state`` singletons.

    Returns a *base* context with infrastructure dependencies. The
    ``app_config`` field is resolved live so per-run fields (e.g.
    ``models[*].max_tokens``) follow ``config.yaml`` edits; the
    ``event_store`` / ``run_events_config`` pair stays frozen to the snapshot
    captured in :func:`langgraph_runtime` so callers never see a store bound
    to one backend paired with a config pointing at another.
    """
    return RunContext(
        checkpointer=get_checkpointer(request),
        store=get_store(request),
        event_store=get_run_event_store(request),
        run_events_config=getattr(request.app.state, "run_events_config", None),

View on GitHub (pinned to 1dd6ba1acb)

Solutions

Resolve the underlying init failure shown in Gateway startup logs (persistence/migrations first)
Confirm mcp_task_repo is also healthy — the service depends on it
Restart the Gateway; both singletons are restart-required and only re-attach at lifespan

Defensive patterns

Strategy: try-catch

Validate before calling

null

Type guard

null

Try / catch

try:
    result = await api.run_mcp_task_action(task_id, action)
except HTTP503 as e:
    if 'MCP task service' in e.detail:
        show_feature_unavailable_banner()
        return
    raise

Prevention

If the repo getter 503s, assume the service will too — fail fast without hammering both
Keep MCP extension config valid; service construction can fail on malformed MCP config
Alert on any 'not available' 503 pattern — it always means a startup defect, not a transient error

When it happens

Trigger: Any route depending on get_mcp_task_service when the service was never constructed during lifespan — usually the same root cause as the missing repo (persistence failure) one layer up.

Common situations: Same as MCP task repo: DB down at startup, incomplete migrations, or tests mounting routers without lifespan; occasionally the service fails alone because of a malformed MCP extension config.

Related errors

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/412a0ca228605630. Report an issue: GitHub.