infiniflow/ragflow · error · InsufficientPermissionsError

Jira credential appears to be invalid or expired (HTTP 401).

Error message

Jira credential appears to be invalid or expired (HTTP 401).

What it means

InsufficientPermissionsError raised by _handle_validation_error when a caught Jira exception exposes status_code == 401. Authentication was attempted and rejected: the API token or basic-auth password is wrong, expired, or revoked. It chains the original exception (from exc) so the server response is inspectable on __cause__.

Source

Thrown at common/data_source/jira/connector.py:281

                attempt_start,
                adjusted_start,
                end,
                self.time_buffer_seconds,
            )
            try:
                return (yield from self._load_from_checkpoint_internal(jql, checkpoint, start_filter=start))
            except Exception as exc:
                if attempt_start is not None and not retried_with_buffer and is_atlassian_date_error(exc):
                    attempt_start = attempt_start - ONE_HOUR
                    retried_with_buffer = True
                    logger.info(f"[Jira] Atlassian date error detected; retrying with start={attempt_start}.")
                    continue
                raise

    def _handle_validation_error(self, exc: Exception) -> None:
        status_code = getattr(exc, "status_code", None)
        if status_code == 401:
            raise InsufficientPermissionsError("Jira credential appears to be invalid or expired (HTTP 401).") from exc
        if status_code == 403:
            raise InsufficientPermissionsError("Jira token does not have permission to access the requested resources (HTTP 403).") from exc
        if status_code == 404:
            raise ConnectorValidationError("Jira resource not found (HTTP 404).") from exc
        if status_code == 429:
            raise ConnectorValidationError("Jira rate limit exceeded during validation (HTTP 429).") from exc

        message = getattr(exc, "text", str(exc))
        if not message:
            raise UnexpectedValidationError("Unexpected Jira validation error.") from exc

        raise ConnectorValidationError(f"Jira validation failed: {message}") from exc

    def _load_from_checkpoint_internal(
        self,
        jql: str,
        checkpoint: JiraCheckpoint,
        start_filter: SecondsSinceUnixEpoch | None = None,

View on GitHub (pinned to 554fb1133a)

Solutions

1. Generate a new API token in Atlassian account settings and update the credential payload.
2. Confirm the token is paired with the correct account (token_auth needs no email; basic_auth needs the exact username).
3. Check __cause__ for the raw response body to confirm the rejection reason (e.g. 'Basic authentication with passwords is deprecated').
4. If using basic auth against Cloud, switch to token_auth - password auth is disabled there.

Example fix

# before
creds = {'jira_user_email': 'dev@acme.com', 'jira_password': 'old-password'}  # Cloud: 401

# after
creds = {'jira_user_email': 'dev@acme.com', 'jira_api_token': os.environ['JIRA_API_TOKEN']}

def jira_token_still_valid(base_url: str, token: str) -> bool:
    import requests
    r = requests.get(f'{base_url.rstrip("/")}/rest/api/3/myself',
                     headers={'Authorization': f'Bearer {token}'}, timeout=10)
    return r.status_code != 401

try:
    connector.validate_connector_settings()
except InsufficientPermissionsError as e:
    if 'HTTP 401' in str(e):
        trigger_credential_renewal(user_id)  # prompt user to re-enter the token
    raise

When it happens

Trigger: validate_connector_settings() or its JQL validation search returning HTTP 401 from the Jira REST API - an expired Atlassian API token, a revoked token, a wrong password, or an email/token mismatch for basic auth.

Common situations: Atlassian API tokens past their expiry policy; tokens revoked when a user leaves or rotates credentials; environment-specific token variables out of sync across deployments; password basic auth against Cloud where it is disabled.

Understand the failure class

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

Related errors

• GitHub credential appears to be invalid or expired (HTTP 401
• Jira credentials must include either an API token or usernam
• Jira: {exc}
• Jira token does not have permission to access the requested
• Provide either an API token or both email/password for Jira

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/b1433e3f2a89a881. Report an issue: GitHub.