{"record":{"id":"97bbf53c7f05efaa","repo":"bytedance/deer-flow","slug":"failed-to-start-lark-connection-setup","errorCode":null,"errorMessage":"Failed to start Lark connection setup.","messagePattern":"Failed to start Lark connection setup\\.","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"backend/app/gateway/routers/integrations.py","lineNumber":304,"sourceCode":"\n@router.post(\"/lark/config/start\", response_model=LarkConfigStartResponse, summary=\"Start Lark/Feishu App Configuration\")\nasync def start_lark_app_config(body: LarkConfigStartRequest) -> LarkConfigStartResponse:\n    try:\n        result = await asyncio.to_thread(\n            start_lark_config,\n            get_effective_user_id(),\n            brand=body.brand,\n        )\n        return _config_start_to_response(result)\n    except FileNotFoundError as e:\n        raise HTTPException(status_code=404, detail=str(e))\n    except ValueError as e:\n        raise HTTPException(status_code=400, detail=str(e))\n    except TimeoutError as e:\n        raise HTTPException(status_code=504, detail=str(e))\n    except Exception as e:\n        logger.error(\"Failed to start Lark connection setup: %s\", e, exc_info=True)\n        raise HTTPException(status_code=500, detail=\"Failed to start Lark connection setup.\")\n\n\n@router.post(\"/lark/config/complete\", response_model=LarkConfigCompleteResponse, summary=\"Complete Lark/Feishu App Configuration\")\nasync def complete_lark_app_config(request: Request, body: LarkConfigCompleteRequest, config: AppConfig = Depends(get_config)) -> LarkConfigCompleteResponse:\n    try:\n        result = await asyncio.to_thread(\n            complete_lark_config,\n            get_effective_user_id(),\n            config,\n            device_code=body.device_code,\n            generation=body.generation,\n            brand=body.brand,\n            interval=body.interval,\n            expires_in=body.expires_in,\n        )\n        return _config_complete_to_response(result, include_host_paths=await _is_admin_user(request))\n    except FileNotFoundError as e:\n        raise HTTPException(status_code=404, detail=str(e))","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/integrations.py#L286-L322","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the Gateway log line 'Failed to start Lark connection setup:' for the traceback","Verify the Gateway can resolve and POST to https://accounts.feishu.cn","Check write permissions on the integration state directory for the Gateway user","Retry once after fixing; a fresh start re-advances the flow generation safely"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { ... } catch (e) {\n  if (e?.response?.status === 500) captureMessage('lark config start failed', { extra: e.response.data });\n}","preventionTips":["Alert on 500s from /lark/config/start and inspect Gateway tracebacks","Verify writable state dirs and network egress in Gateway health checks"],"tags":["lark","feishu","http-500","gateway","network","filesystem"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}