bytedance/deer-flow · error · HTTPException

Failed to install Lark integration.

Error message

Failed to install Lark integration.

What it means

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).

Source

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

        raise HTTPException(status_code=500, detail="Failed to get Lark integration status.")


@router.post("/lark/install", response_model=LarkInstallResponse, summary="Install Lark/Feishu Skill Pack")
async def install_lark(request: Request, config: AppConfig = Depends(get_config)) -> LarkInstallResponse:
    await require_admin_user(request, detail=_ADMIN_REQUIRED_DETAIL)
    try:
        result = await asyncio.to_thread(install_lark_integration, get_effective_user_id(), config)
        await refresh_skills_system_prompt_cache_async()
        return _install_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 HTTPException:
        raise
    except Exception as e:
        logger.error("Failed to install Lark integration: %s", e, exc_info=True)
        raise HTTPException(status_code=500, detail="Failed to install Lark integration.")


@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:

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Check Gateway logs for the 'Failed to install Lark integration:' line with full traceback to identify the real exception
2. Verify network egress from the Gateway container to npm registry and GitHub release hosts
3. Confirm the integration skills directory is writable and not full (df -h on the Gateway)
4. If using aio_sandbox, verify the resolved lark-cli version tag is valid and sandbox dirs are writable
5. As a workaround, set LARK_CLI_SOURCE_ARCHIVE to a pre-downloaded archive path reachable by the Gateway

const status = await api.get('/integrations/lark/status');
if (!status.data.installed) { /* surface install prerequisite to admin */ }

function isHttpError(e: unknown, code: number): e is { status: number; detail: string } {
  return typeof e === 'object' && e !== null && (e as any).status === code;
}

try {
  await api.post('/integrations/lark/install');
} catch (e) {
  if (axios.isAxiosError(e) && e.response?.status === 500) {
    // opaque; instruct operator to check Gateway logs
    report('Install failed. See Gateway logs for the traceback.');
  } else throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Failed to start Lark connection setup.
• Failed to complete Lark connection setup.
• 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/922c88aaaf1c9487. Report an issue: GitHub.