bytedance/deer-flow · error · HTTPException

Model '{model_name}' is not available for your role

Error message

Model '{model_name}' is not available for your role

What it means

Raised as HTTP 403 by GET /api/models/{model_name} when the authorization provider could not be reached/resolved (_AuthorizationUnavailable) and config.authorization.fail_closed is true. The model exists; access is denied because the system cannot confirm permission and is configured to deny on uncertainty.

Source

Thrown at backend/app/gateway/routers/models.py:180

            "description": "OpenAI GPT-4 model",
            "supports_thinking": false
        }
        ```
    """
    model = config.get_model_config(model_name)
    if model is None:
        raise HTTPException(status_code=404, detail=f"Model '{model_name}' not found")

    # Phase 3: enforce model:use authorization (deny → 403, not 404, since the
    # model exists but the role lacks permission to use it).
    fail_closed = config.authorization.fail_closed
    user = await get_optional_user_from_request(request)
    if user is not None:
        try:
            provider, principal = resolve_model_authorization(user, is_internal=_is_internal_caller(request, user))
        except _AuthorizationUnavailable:
            if fail_closed:
                raise HTTPException(status_code=403, detail=f"Model '{model_name}' is not available for your role")
        else:
            if provider is not None and principal is not None:
                try:
                    decision = provider.authorize(AuthzRequest(principal=principal, resource="model", action="use", target=model_name))
                    if not isinstance(decision, AuthzDecision):
                        raise TypeError("AuthorizationProvider.authorize must return AuthzDecision")
                    allowed = decision.allow
                except Exception:
                    logger.warning(
                        "Authorization provider failed while checking model:use for %s",
                        model_name,
                        exc_info=True,
                    )
                    allowed = not fail_closed
                if not allowed:
                    raise HTTPException(status_code=403, detail=f"Model '{model_name}' is not available for your role")

    return ModelResponse(

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Fix or register the AuthorizationProvider so resolve_model_authorization succeeds (check gateway startup logs for provider load errors).
2. If the deployment intentionally has no authorization, set authorization.fail_closed: false (or disable the authorization block) in config.yaml and restart the Gateway.
3. If fail-closed is intended, restore the auth backend the provider depends on.

Example fix

# config.yaml — before
authorization:
  fail_closed: true   # provider unavailable -> 403
# after (no auth provider deployed)
authorization:
  fail_closed: false

# preflight: does the gateway resolve authorization for this token?
me = requests.get(f"{BASE}/api/me", headers=auth)  # or any authed endpoint
assert me.status_code != 403, "authz stack unavailable; fail_closed will deny model access"

resp = requests.get(f"{BASE}/api/models/{model_name}", headers=auth)
if resp.status_code == 403:
    detail = resp.json()["detail"]
    if "not available for your role" in detail:
        # distinguish infra failure from policy deny via gateway logs,
        # then fall back to a known-allowed default model
        switch_to_default_model()

When it happens

Trigger: Requesting a valid model while the AuthorizationProvider is unregistered/misconfigured, and fail_closed: true is set in config.yaml. The provider lookup throws before any authorize() call.

Common situations: Enabling fail-closed authorization without wiring an auth provider; auth extension disabled but authorization config still active; internal auth service dependency down at startup.

Related errors

• Permission denied: {resource}:{action}
• {detail}
• Custom-agent management API is disabled. Set agents_api.enab
• Unknown model '{model}'. Use a model name defined under `mod
• registration_disabled

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