BerriAI/litellm · error · Exception

Authentication failed. Check your GitLab token and auth_meth

Error message

Authentication failed. Check your GitLab token and auth_method.

What it means

Raised by GitLabClient._get_file_content_via_raw when the GitLab raw-file API returns HTTP 401: authentication failed — the token is missing, malformed, expired, or revoked. Headers are built in __init__ based on auth_method ('token' sends Private-Token; 'oauth' sends Authorization: Bearer).

Source

Thrown at litellm/integrations/gitlab/gitlab_client.py:149

            ctype: Final = (resp.headers.get("content-type") or "").lower()
            if ctype.startswith("text/") or "charset=" in ctype or ctype.startswith("application/json"):
                return resp.text
            try:
                return resp.content.decode("utf-8")
            except Exception:
                return resp.content.decode("utf-8", errors="replace")

        except Exception as e:
            status: Final = getattr(getattr(e, "response", None), "status_code", None)
            if status == 404:
                return None
            if status == 403:
                raise Exception(
                    f"Access denied to file '{file_path}'. Check your GitLab permissions for project '{self.project}'."
                )
            if status == 401:
                raise Exception("Authentication failed. Check your GitLab token and auth_method.")
            raise Exception(f"Failed to fetch file '{file_path}': {e}")

    def _get_file_content_via_json(self, file_path: str, *, ref: str | None = None) -> str | None:
        """
        Fallback for get_file_content(): use the JSON file API which returns base64 content.
        """
        json_url: Final = self._file_json_url(file_path, ref=ref)
        try:
            resp: Final = self.http_handler.get(json_url, headers=self.headers)
            if resp.status_code == 404:
                return None
            resp.raise_for_status()
            data: Final = resp.json()
            content: Final = data.get("content")
            encoding: Final = data.get("encoding", "")
            if content and encoding == "base64":
                try:
                    return base64.b64decode(content).decode("utf-8")

View on GitHub (pinned to 6c2dcb801b)

Solutions

Test the token directly: curl -H 'Private-Token: <token>' 'https://gitlab.com/api/v4/user' — 401 means the token itself is bad.
If auth_method is 'oauth', supply an OAuth/Bearer-capable token or switch auth_method to 'token' for PATs.
Regenerate/rotate the token and update the environment variable or config backing access_token, then restart the service.

Example fix

# before
gitlab_config = {
  "project": "acme/prompts",
  "access_token": "glpat-...",
  "auth_method": "oauth",  # PAT is not a Bearer token -> 401
}

# after
gitlab_config = {
  "project": "acme/prompts",
  "access_token": "glpat-...",
  "auth_method": "token",
}

Defensive patterns

Strategy: try-catch

Validate before calling

import httpx

def verify_gitlab_token(base_url: str, token: str, auth_method: str = "token") -> None:
    header = {"Authorization": f"Bearer {token}"} if auth_method == "oauth" else {"Private-Token": token}
    resp = httpx.get(f"{base_url}/user", headers=header, timeout=10)
    if resp.status_code == 401:
        raise PermissionError("GitLab token is invalid, expired, or wrong auth_method")

Try / catch

try:
    content = client.get_file_content("chat/greet.prompt")
except Exception as e:
    if "Authentication failed" in str(e):
        rotate_gitlab_token()  # alert + refresh from secret store
        raise
    raise

Prevention

Verify tokens with GET /user during startup health checks.
Match auth_method to token type: 'token' for PATs/deploy tokens, 'oauth' for OAuth tokens.
Set expiry reminders for PATs and automate rotation before expiry.

When it happens

Trigger: Expired or revoked personal access token; auth_method set to 'oauth' while supplying a PAT (PATs are not Bearer JWTs, so GitLab rejects them); token string with stray whitespace or a truncated copy-paste; project access token rotated on the server but not in litellm config.

Common situations: GitLab PATs expiring on their enforced schedule (admins often cap at 1 year or less); tokens rotated by a security team without updating the proxy's environment; switching between auth methods without changing the token type.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/c8adce079f382b92. Report an issue: GitHub.