infiniflow/ragflow · error · InsufficientPermissionsError

Jira token does not have permission to access the requested

Error message

Jira token does not have permission to access the requested resources (HTTP 403).

What it means

InsufficientPermissionsError raised by _handle_validation_error when the Jira exception carries status_code == 403. Authentication succeeded but the authenticated identity lacks permission for the request - the token's scopes, the user's project roles, or admin-tier requirements block the operation. Chained from the original exception for response details.

Source

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

                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,
    ) -> Generator[Document | ConnectorFailure, None, JiraCheckpoint]:
        assert self.jira_client, "load_credentials must be called before loading issues."

View on GitHub (pinned to 554fb1133a)

Solutions

1. Grant the identity read access (Browse Projects plus view issues/comments) on the target project, or use a token with broader scopes.
2. Narrow the jql_query or project_key to resources the identity can access.
3. Inspect the __cause__ response text - Jira names the missing permission.
4. If scoped_token=True, verify the token's scopes include read for Jira on that site.

Example fix

# before
connector = JiraConnector(jira_base_url=url, jql_query='project = SECRET')  # user lacks access -> 403

# after
# (admin) add the user to project SECRET with role 'Users', or narrow the scope:
connector = JiraConnector(jira_base_url=url, jql_query='project = OPS')

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

try:
    connector.validate_connector_settings()
except InsufficientPermissionsError as e:
    if 'HTTP 403' in str(e):
        log.warning('Token authenticated but lacks access; check project roles/scopes: %s', e.__cause__)
    raise

When it happens

Trigger: A scoped or automation token without read scope for the target project; a user who is not a member of the project; a JQL query referencing projects the identity cannot see; fetching comments or attachments where the identity has issue-view but not comment-view rights.

Common situations: Scoped tokens created for one product or site and used on another; service accounts added to Jira but not granted the project role; org-level restrictions on automation tokens.

Understand the failure class

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

Related errors

• main() must return a value. Use null for an empty result.
• Insufficient permissions to access Bitbucket workspace (HTTP
• message.compileNotSupported
• Azure Blob: insufficient permissions on container: {msg[:300
• The calling user does not have permission

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