infiniflow/ragflow · error · UnexpectedValidationError

Unexpected Jira validation error.

Error message

Unexpected Jira validation error.

What it means

UnexpectedValidationError raised by _handle_validation_error when the caught Jira exception has no recognizable status_code and its text/str() yields an empty message. It is the catch-all branch: the library surfaced an exception with no HTTP status and no text, so this wrapper exists to guarantee the error chain is not silent. Inspect __cause__ to identify the real exception type.

Source

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

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

        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(

View on GitHub (pinned to 554fb1133a)

Solutions

1. Inspect the chained cause: repr(e.__cause__) and its traceback reveal the underlying exception type and origin.
2. Reproduce the validation call in isolation with debug logging on the jira client to capture the raw failure.
3. Upgrade or pin the jira library to a version whose exceptions reliably carry status_code.
4. Check for network or proxy issues between the worker and Jira if the cause is transport-level.

Example fix

# before
try:
    connector.validate_connector_settings()
except UnexpectedValidationError:
    pass  # cause invisible

# after
try:
    connector.validate_connector_settings()
except UnexpectedValidationError as e:
    logging.exception('Jira validation failed; cause=%r', e.__cause__)
    raise

try:
    connector.validate_connector_settings()
except UnexpectedValidationError as e:
    log.exception('Jira validation failed with empty message; underlying cause: %r', e.__cause__)
    raise

When it happens

Trigger: A jira-library exception raised client-side before an HTTP response existed (for example a socket error wrapped in a status-less type), or a response object whose text attribute is empty - e.g. an empty body with an unusual status code, or a non-HTTP exception escaping during validation.

Common situations: Network resets producing bare exceptions; version changes in the jira library altering exception attributes; proxy interference stripping response bodies.

Related errors

• Unexpected S3 client error (code={error_code}, status={statu
• Jira base URL must be provided.
• Invalid time_buffer_seconds value ({time_buffer_seconds!r});
• {exc}
• Jira resource not found (HTTP 404).

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