bytedance/deer-flow · error · HTTPException

Failed to start Lark connection setup.

Error message

Failed to start Lark connection setup.

What it means

Generic 500 catch-all for POST /lark/config/start (integrations.py:304). Any exception from start_lark_config not classified as FileNotFoundError/ValueError/TimeoutError — e.g. urllib URLError wrapping a DNS failure, JSON decode errors, or lock-file OSError — is logged with traceback and returned as this opaque 500.

Source

Thrown at backend/app/gateway/routers/integrations.py:304

@router.post("/lark/config/start", response_model=LarkConfigStartResponse, summary="Start Lark/Feishu App Configuration")
async def start_lark_app_config(body: LarkConfigStartRequest) -> LarkConfigStartResponse:
    try:
        result = await asyncio.to_thread(
            start_lark_config,
            get_effective_user_id(),
            brand=body.brand,
        )
        return _config_start_to_response(result)
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except TimeoutError as e:
        raise HTTPException(status_code=504, detail=str(e))
    except Exception as e:
        logger.error("Failed to start Lark connection setup: %s", e, exc_info=True)
        raise HTTPException(status_code=500, detail="Failed to start Lark connection setup.")


@router.post("/lark/config/complete", response_model=LarkConfigCompleteResponse, summary="Complete Lark/Feishu App Configuration")
async def complete_lark_app_config(request: Request, body: LarkConfigCompleteRequest, config: AppConfig = Depends(get_config)) -> LarkConfigCompleteResponse:
    try:
        result = await asyncio.to_thread(
            complete_lark_config,
            get_effective_user_id(),
            config,
            device_code=body.device_code,
            generation=body.generation,
            brand=body.brand,
            interval=body.interval,
            expires_in=body.expires_in,
        )
        return _config_complete_to_response(result, include_host_paths=await _is_admin_user(request))
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Read the Gateway log line 'Failed to start Lark connection setup:' for the traceback
2. Verify the Gateway can resolve and POST to https://accounts.feishu.cn
3. Check write permissions on the integration state directory for the Gateway user
4. Retry once after fixing; a fresh start re-advances the flow generation safely

try { ... } catch (e) {
  if (e?.response?.status === 500) captureMessage('lark config start failed', { extra: e.response.data });
}

When it happens

Trigger: socket.gaierror/URLError from unreachable accounts.feishu.cn, permission errors writing the per-user Lark flow state file, or an unexpected response shape from the begin endpoint.

Common situations: Gateway running with a read-only home directory, SELinux denying writes to the credential tree, or transient network errors that raise URLError instead of a timeout.

Related errors

• Failed to complete Lark connection setup.
• Failed to install Lark integration.
• Failed to switch Lark app credentials.
• Failed to start Lark authorization.
• Failed to get Lark integration status.

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