crewAIInc/crewAI · error · HTTPException

Token introspection service unavailable

Error message

Token introspection service unavailable

What it means

Raised by OAuth2ServerAuth._authenticate_introspection() when the RFC 7662 introspection endpoint returns an HTTP error status (response.raise_for_status() throws httpx.HTTPStatusError). It maps to HTTP 503 Service Unavailable — the token was never evaluated because the upstream IdP rejected the introspection call itself. Logged at ERROR level with the upstream status code as reason='http_error'.

Source

Thrown at lib/crewai/src/crewai/a2a/auth/server_schemes.py:607

                response = await client.post(
                    str(self.introspection_url),
                    data={"token": token},
                    auth=(
                        self.introspection_client_id or "",
                        self.introspection_client_secret.get_secret_value()
                        if self.introspection_client_secret
                        else "",
                    ),
                )
                response.raise_for_status()
                introspection_result = response.json()

        except httpx.HTTPStatusError as e:
            logger.error(
                "OAuth2 introspection failed",
                extra={"reason": "http_error", "status_code": e.response.status_code},
            )
            raise HTTPException(
                status_code=HTTP_503_SERVICE_UNAVAILABLE,
                detail="Token introspection service unavailable",
            ) from None
        except Exception as e:
            logger.error(
                "OAuth2 introspection failed",
                extra={"reason": "unexpected_error", "error": str(e)},
            )
            raise HTTPException(
                status_code=HTTP_503_SERVICE_UNAVAILABLE,
                detail="Token introspection failed",
            ) from None

        if not introspection_result.get("active", False):
            logger.debug(
                "OAuth2 authentication failed",
                extra={"reason": "token_not_active", "scheme": "oauth2"},
            )

View on GitHub (pinned to 754d7323be)

Solutions

1. Check the logged status_code: 401/403 means bad client credentials — re-register the client and update introspection_client_id/secret.
2. 429 means rate limiting — add backoff/retry with jitter on the caller side or raise IdP quotas.
3. 5xx/404 — verify the introspection_url against the IdP's current documentation.
4. Retry the original request after a short delay for transient upstream failures.

Example fix

# before
auth = OAuth2ServerAuth(
    introspection_url="https://idp/v1/introspect",  # wrong/legacy path -> 404 -> 503
    introspection_client_id="svc", introspection_client_secret=secret,
)

# after
auth = OAuth2ServerAuth(
    introspection_url="https://idp/oauth2/v1/introspect",  # IdP's documented endpoint
    introspection_client_id="svc", introspection_client_secret=secret,
)

import httpx

probe = httpx.post(
    introspection_url,
    data={"token": "probe-token"},
    auth=(introspection_client_id, introspection_client_secret),
    timeout=5,
)
assert probe.status_code == 200, (
    f"introspection endpoint unhealthy: {probe.status_code} (401/403 = bad client credentials)"
)

for attempt in range(3):
    try:
        return await scheme.authenticate(token)
    except HTTPException as e:
        if e.status_code == 503 and e.detail == "Token introspection service unavailable":
            await asyncio.sleep(2 ** attempt)  # upstream IdP error: backoff and retry
        else:
            raise

When it happens

Trigger: Introspection endpoint returns 401 because introspection_client_id/client_secret are wrong (the call is authenticated with HTTP basic auth); 429 rate limiting; 5xx from the IdP; the URL points to a wrong path returning 404.

Common situations: Rotated or revoked introspection client credentials; IdP rate limits hit under load; wrong introspection URL copied from docs (v1 vs v2 endpoints); IdP partial outage.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

• Error. A valid pyproject.toml file is required. Check that a
• Unable to fetch signing keys
• introspection_client_id and introspection_client_secret are
• OAuth2 introspection not configured
• Error: {e}

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/86f1fbc90ed8e363. Report an issue: GitHub.