infiniflow/ragflow · error · ConnectorValidationError

Jira validation failed: {message}

Error message

Jira validation failed: {message}

What it means

Thrown by the Jira connector's validate_connector_settings as a ConnectorValidationError when the Jira HTTP request fails with a status code not explicitly mapped (i.e. not 401/403/404/429) and the response body contains some text. The message interpolates the raw response text from the exception, so the upstream Jira server error is surfaced verbatim. It is the catch-all 'other HTTP error' branch of credential validation.

Source

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

                    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."

        page_size = self._full_page_size()
        new_checkpoint = copy.deepcopy(checkpoint)
        starting_offset = new_checkpoint.start_at or 0
        current_offset = starting_offset
        checkpoint_callback = self._make_checkpoint_callback(new_checkpoint)

        issue_iter = self._perform_jql_search(
            jql=jql,
            start=current_offset,

View on GitHub (pinned to 554fb1133a)

Solutions

  1. Inspect the interpolated {message} text — it is the raw response body from Jira and names the real problem (e.g. 'XSRF check failed', '502 Bad Gateway').
  2. If the message mentions gateway/proxy/502/503, verify base_url points directly at the Jira instance REST endpoint (e.g. https://yourorg.atlassian.net) and retry once the service is back.
  3. If it is a 400-class message, check credential shape: API token with email, or scoped token configured correctly; confirm no stale cookies/headers are injected by a proxy.
  4. Reproduce with curl -u email:token <base_url>/rest/api/2/myself to see the exact status and body outside the connector.

Example fix

# before
connector.load_credentials({"jira_user_email": email, "jira_api_token": token})
connector.validate_connector_settings()  # raises ConnectorValidationError('Jira validation failed: ...')

# after
from onyx.configs.constants import ...  # adjust import to your tree
try:
    connector.validate_connector_settings()
except ConnectorValidationError as exc:
    logging.error("Jira validation failed: %s", exc)
    raise
Defensive patterns

Strategy: try-catch

Validate before calling

import requests

def jira_reachable(base_url: str, email: str, token: str) -> bool:
    r = requests.get(f"{base_url}/rest/api/2/myself", auth=(email, token), timeout=10)
    return r.status_code == 200

Try / catch

try:
    connector.validate_connector_settings()
except InsufficientPermissionsError:
    ...  # 401/403: credential problem
except ConnectorValidationError as exc:
    # includes 'Jira validation failed: {message}' catch-all
    log_and_surface(str(exc))

Prevention

When it happens

Trigger: Calling connector.validate_connector_settings() (directly or via load_credentials-driven validation flows) when the Jira REST API returns any non-2xx status other than 401/403/404/429 with a non-empty body — e.g. 400 Bad Request from a malformed base_url, 500/502/503 from Jira, or a proxy returning an HTML error page with a status like 502.

Common situations: Misconfigured base_url pointing to a load balancer or SSO gateway that returns 4xx/5xx; Jira Cloud/Data Center outage or maintenance window returning 503; corporate proxy intercepting the request; auth scheme mismatch (scoped token vs basic auth) producing 400.

Related errors

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