{"record":{"id":"922c88aaaf1c9487","repo":"bytedance/deer-flow","slug":"failed-to-install-lark-integration","errorCode":null,"errorMessage":"Failed to install Lark integration.","messagePattern":"Failed to install Lark integration\\.","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"backend/app/gateway/routers/integrations.py","lineNumber":284,"sourceCode":"        raise HTTPException(status_code=500, detail=\"Failed to get Lark integration status.\")\n\n\n@router.post(\"/lark/install\", response_model=LarkInstallResponse, summary=\"Install Lark/Feishu Skill Pack\")\nasync def install_lark(request: Request, config: AppConfig = Depends(get_config)) -> LarkInstallResponse:\n    await require_admin_user(request, detail=_ADMIN_REQUIRED_DETAIL)\n    try:\n        result = await asyncio.to_thread(install_lark_integration, get_effective_user_id(), config)\n        await refresh_skills_system_prompt_cache_async()\n        return _install_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 HTTPException:\n        raise\n    except Exception as e:\n        logger.error(\"Failed to install Lark integration: %s\", e, exc_info=True)\n        raise HTTPException(status_code=500, detail=\"Failed to install Lark integration.\")\n\n\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:","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/integrations.py#L266-L302","documentation":"Generic 500 from the catch-all handler of POST /lark/install (backend/app/gateway/routers/integrations.py:284). install_lark_integration (lark_cli.py:936) downloads the Lark skills archive, installs skills, and optionally provisions a sandbox CLI; any exception not mapped to 404/400 (e.g. archive download failure, disk error, aio_sandbox provisioning crash) is logged with a traceback and returned as this opaque 500. The real cause is only visible in the Gateway log via logger.error(..., exc_info=True).","triggerScenarios":"POST /lark/install when the Gateway cannot reach GitHub/npm to download the @larksuite/cli archive, when the skills archive is corrupt or its manifest sha mismatches, or when config.yaml enables aio_sandbox without a provisioner_url and the sandbox CLI install fails (invalid version tag, missing binary).","commonSituations":"Egress-restricted Gateway containers blocking npm/GitHub, read-only or full filesystem where the managed CLI is installed, an invalid LARK_CLI_SOURCE_ARCHIVE env var pointing at a bad archive, or a sandbox.provisioner_url configured but unreachable.","solutions":["Check Gateway logs for the 'Failed to install Lark integration:' line with full traceback to identify the real exception","Verify network egress from the Gateway container to npm registry and GitHub release hosts","Confirm the integration skills directory is writable and not full (df -h on the Gateway)","If using aio_sandbox, verify the resolved lark-cli version tag is valid and sandbox dirs are writable","As a workaround, set LARK_CLI_SOURCE_ARCHIVE to a pre-downloaded archive path reachable by the Gateway"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const status = await api.get('/integrations/lark/status');\nif (!status.data.installed) { /* surface install prerequisite to admin */ }","typeGuard":"function isHttpError(e: unknown, code: number): e is { status: number; detail: string } {\n  return typeof e === 'object' && e !== null && (e as any).status === code;\n}","tryCatchPattern":"try {\n  await api.post('/integrations/lark/install');\n} catch (e) {\n  if (axios.isAxiosError(e) && e.response?.status === 500) {\n    // opaque; instruct operator to check Gateway logs\n    report('Install failed. See Gateway logs for the traceback.');\n  } else throw e;\n}","preventionTips":["Pre-install the managed integration in deployment provisioning rather than at user runtime","Keep LARK_CLI_SOURCE_ARCHIVE pinned to a mirrored archive for air-gapped environments","Monitor Gateway logs for 'Failed to install Lark integration' alerting"],"tags":["lark","feishu","integration","http-500","install","gateway"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}