{"record":{"id":"e3c32b2a734b9234","repo":"infiniflow/ragflow","slug":"unexpected-jira-validation-error","errorCode":null,"errorMessage":"Unexpected Jira validation error.","messagePattern":"Unexpected Jira validation error\\.","errorType":"validation","errorClass":"UnexpectedValidationError","httpStatus":null,"severity":"error","filePath":"common/data_source/jira/connector.py","lineNumber":291,"sourceCode":"                    retried_with_buffer = True\n                    logger.info(f\"[Jira] Atlassian date error detected; retrying with start={attempt_start}.\")\n                    continue\n                raise\n\n    def _handle_validation_error(self, exc: Exception) -> None:\n        status_code = getattr(exc, \"status_code\", None)\n        if status_code == 401:\n            raise InsufficientPermissionsError(\"Jira credential appears to be invalid or expired (HTTP 401).\") from exc\n        if status_code == 403:\n            raise InsufficientPermissionsError(\"Jira token does not have permission to access the requested resources (HTTP 403).\") from exc\n        if status_code == 404:\n            raise ConnectorValidationError(\"Jira resource not found (HTTP 404).\") from exc\n        if status_code == 429:\n            raise ConnectorValidationError(\"Jira rate limit exceeded during validation (HTTP 429).\") from exc\n\n        message = getattr(exc, \"text\", str(exc))\n        if not message:\n            raise UnexpectedValidationError(\"Unexpected Jira validation error.\") from exc\n\n        raise ConnectorValidationError(f\"Jira validation failed: {message}\") from exc\n\n    def _load_from_checkpoint_internal(\n        self,\n        jql: str,\n        checkpoint: JiraCheckpoint,\n        start_filter: SecondsSinceUnixEpoch | None = None,\n    ) -> Generator[Document | ConnectorFailure, None, JiraCheckpoint]:\n        assert self.jira_client, \"load_credentials must be called before loading issues.\"\n\n        page_size = self._full_page_size()\n        new_checkpoint = copy.deepcopy(checkpoint)\n        starting_offset = new_checkpoint.start_at or 0\n        current_offset = starting_offset\n        checkpoint_callback = self._make_checkpoint_callback(new_checkpoint)\n\n        issue_iter = self._perform_jql_search(","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/jira/connector.py#L273-L309","documentation":"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.","triggerScenarios":"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.","commonSituations":"Network resets producing bare exceptions; version changes in the jira library altering exception attributes; proxy interference stripping response bodies.","solutions":["Inspect the chained cause: repr(e.__cause__) and its traceback reveal the underlying exception type and origin.","Reproduce the validation call in isolation with debug logging on the jira client to capture the raw failure.","Upgrade or pin the jira library to a version whose exceptions reliably carry status_code.","Check for network or proxy issues between the worker and Jira if the cause is transport-level."],"exampleFix":"# before\ntry:\n    connector.validate_connector_settings()\nexcept UnexpectedValidationError:\n    pass  # cause invisible\n\n# after\ntry:\n    connector.validate_connector_settings()\nexcept UnexpectedValidationError as e:\n    logging.exception('Jira validation failed; cause=%r', e.__cause__)\n    raise","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    connector.validate_connector_settings()\nexcept UnexpectedValidationError as e:\n    log.exception('Jira validation failed with empty message; underlying cause: %r', e.__cause__)\n    raise","preventionTips":["Always log e.__cause__ for this wrapper - the message is empty by construction.","Pin the jira library version so exception shapes (status_code/text attributes) stay predictable.","Reproduce validation calls in isolation with HTTP debug logging when the cause is unclear."],"tags":["jira","validation","unknown-error","diagnostics"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}