{"record":{"id":"533735932af921a4","repo":"infiniflow/ragflow","slug":"jira-exc","errorCode":null,"errorMessage":"Jira: {exc}","messagePattern":"Jira: \\{exc\\}","errorType":"validation","errorClass":"ConnectorMissingCredentialError","httpStatus":null,"severity":"error","filePath":"common/data_source/jira/connector.py","lineNumber":181,"sourceCode":"                    basic_auth=(user_email, api_token),\n                    options=options,\n                )\n            elif api_token:\n                self.jira_client = JIRA(\n                    server=jira_url_for_client,\n                    token_auth=api_token,\n                    options=options,\n                )\n            elif user_email and password:\n                self.jira_client = JIRA(\n                    server=jira_url_for_client,\n                    basic_auth=(user_email, password),\n                    options=options,\n                )\n            else:\n                raise ConnectorMissingCredentialError(\"Jira credentials must include either an API token or username/password.\")\n        except Exception as exc:  # pragma: no cover - jira lib raises many types\n            raise ConnectorMissingCredentialError(f\"Jira: {exc}\") from exc\n        self._sync_timezone_from_server()\n        return None\n\n    def validate_connector_settings(self) -> None:\n        \"\"\"Validate connectivity by fetching basic Jira info.\"\"\"\n        if not self.jira_client:\n            raise ConnectorMissingCredentialError(\"Jira\")\n\n        try:\n            if self.jql_query:\n                dummy_checkpoint = self.build_dummy_checkpoint()\n                checkpoint_callback = self._make_checkpoint_callback(dummy_checkpoint)\n                iterator = self._perform_jql_search(\n                    jql=self.jql_query,\n                    start=0,\n                    max_results=1,\n                    fields=\"key\",\n                    all_issue_ids=dummy_checkpoint.all_issue_ids,","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/jira/connector.py#L163-L199","documentation":"ConnectorMissingCredentialError raised when the jira library's JIRA(...) constructor itself throws while building the client (network error, credentials rejected at first contact, invalid server URL, unsupported rest_api_version). The original message is preserved as 'Jira: {exc}'. The comment 'pragma: no cover - jira lib raises many types' signals the library has a wide exception surface, so the message text is the best diagnostic.","triggerScenarios":"JIRA(server=..., token_auth=...) with an unreachable server, an expired or revoked token, a rest_api_version the server rejects, or SSL failures. Any Exception escaping the two JIRA(...) construction branches lands here.","commonSituations":"Atlassian token rotated or expired without updating config; on-prem Jira behind a VPN not reachable from the worker; rest_api_version forced to a value the instance does not support.","solutions":["Read the text after 'Jira: ' - it is the underlying cause (e.g. 401 from Atlassian, connection refused, SSLError).","Verify the token and credentials with curl against the same REST endpoint the client would use.","Confirm network reachability (VPN, firewall, DNS) from the host running the connector.","If rest_api_version was supplied in credentials, try omitting it so the default is used."],"exampleFix":"# before\ncreds = {'jira_api_token': 'expired-token', 'rest_api_version': '2'}\nconnector.load_credentials(creds)  # Jira: 401 ...\n\n# after\ncreds = {'jira_api_token': os.environ['JIRA_API_TOKEN']}  # fresh token, default API version\nconnector.load_credentials(creds)","handlingStrategy":"try-catch","validationCode":"def jira_server_reachable(base_url: str, timeout: float = 5.0) -> bool:\n    import requests\n    try:\n        return requests.get(base_url, timeout=timeout).status_code < 500\n    except requests.RequestException:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    connector.load_credentials(creds)\nexcept ConnectorMissingCredentialError as e:\n    cause = e.__cause__\n    log.error('Jira client construction failed: %s', cause)\n    if jira_server_reachable(connector.jira_base_url):\n        mark_token_invalid(creds)  # server up but auth rejected -> rotate token\n    raise","preventionTips":["Health-check reachability from the worker network before constructing JIRA clients.","Track token issuance dates and rotate Atlassian API tokens proactively.","Keep the wrapped cause in logs - the 'Jira: ' prefix alone loses the exception type."],"tags":["jira","credentials","network","authentication"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}