bytedance/deer-flow · error · HTTPException

Failed to complete Lark authorization.

Error message

Failed to complete Lark authorization.

What it means

Generic 500 returned when complete_lark_auth raises an unexpected exception (anything outside FileNotFoundError/LarkFlowSupersededError/ValueError/TimeoutError). The original exception is logged server-side with a full traceback; the client intentionally gets only the static message, so no internal details leak.

Source

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

            complete_lark_auth,
            get_effective_user_id(),
            config,
            device_code=body.device_code,
            generation=body.generation,
            wait_timeout_seconds=body.wait_timeout_seconds,
        )
        return _auth_complete_to_response(result, include_host_paths=await _is_admin_user(request))
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except LarkFlowSupersededError as e:
        raise HTTPException(status_code=409, 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 complete Lark authorization: %s", e, exc_info=True)
        raise HTTPException(status_code=500, detail="Failed to complete Lark authorization.")

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Check the Gateway logs for the logged traceback ('Failed to complete Lark authorization') — it names the real cause
2. Verify the Lark integration credentials (app_id/app_secret) in config.yaml and that the app has the required scopes
3. Confirm network egress from the Gateway host to open.feishu.cn
4. If the traceback points to state-file corruption, clear the stale Lark auth state and restart the flow

Example fix

// client: distinguish real 500s from retryable waits
// before
if (!res.ok) throw new Error(await res.text());
// after
if (res.status === 500) { console.error('server-side failure; check Gateway logs'); await restartFlow(); } else if (!res.ok) throw new Error(await res.text());

null

null

try { return await complete(body); } catch (e) { if (e.status === 500) { await delay(backoff(attempt++)); if (attempt <= 3) return completeFreshFlow(); } throw e; }

When it happens

Trigger: Lark/Feishu API returns an unexpected error shape during token exchange, the configured Lark app credentials (app_id/app_secret) are wrong or missing, network failures to the Lark open-platform, or bugs in the auth state serialization code.

Common situations: Misconfigured Lark integration in config.yaml (invalid app secret); Lark API outage or rate limiting; expired/revoked Feishu app credentials; disk-full or permission errors writing token state.

Related errors

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

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