{"record":{"id":"03fa5a912e345301","repo":"infiniflow/ragflow","slug":"either-project-key-or-jql-query-must-be-provided-f","errorCode":null,"errorMessage":"Either project_key or jql_query must be provided for Jira connector.","messagePattern":"Either project_key or jql_query must be provided for Jira connector\\.","errorType":"validation","errorClass":"ConnectorValidationError","httpStatus":null,"severity":"error","filePath":"common/data_source/jira/connector.py","lineNumber":438,"sourceCode":"                page_size=_JIRA_SLIM_PAGE_SIZE,\n            )\n            prev_offset = current_offset\n\n        if slim_batch:\n            yield slim_batch\n\n    # -------------------------------------------------------------------------\n    # Internal helpers\n    # -------------------------------------------------------------------------\n\n    def _build_jql(self, start: SecondsSinceUnixEpoch, end: SecondsSinceUnixEpoch) -> str:\n        clauses: list[str] = []\n        if self.jql_query:\n            clauses.append(f\"({self.jql_query})\")\n        elif self.project_key:\n            clauses.append(f'project = \"{self.project_key}\"')\n        else:\n            raise ConnectorValidationError(\"Either project_key or jql_query must be provided for Jira connector.\")\n\n        if self.labels_to_skip:\n            labels = \", \".join(f'\"{label}\"' for label in self.labels_to_skip)\n            clauses.append(f\"labels NOT IN ({labels})\")\n\n        adjusted_start = self._adjust_start_for_query(start)\n        if adjusted_start is not None:\n            clauses.append(f'updated >= \"{self._format_jql_time(adjusted_start)}\"')\n        if end is not None:\n            clauses.append(f'updated <= \"{self._format_jql_time(end)}\"')\n\n        if not clauses:\n            raise ConnectorValidationError(\"Unable to build Jira JQL query.\")\n\n        jql = \" AND \".join(clauses)\n        if \"order by\" not in jql.lower():\n            jql = f\"{jql} ORDER BY updated ASC\"\n        return jql","sourceCodeStart":420,"sourceCodeEnd":456,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/jira/connector.py#L420-L456","documentation":"A ConnectorValidationError raised inside _build_jql when neither self.jql_query nor self.project_key is set, so no base clause can be constructed for the JQL search query. It is a configuration error: the connector was instantiated without one of its two mutually-exclusive required selection options.","triggerScenarios":"Constructing JiraConnector with both project_key=None (or omitted) and jql_query=None (or omitted), then triggering any load path that builds JQL — load_from_checkpoint, poll_source, or retrieve_all_slim_docs_perm_sync — all of which call _build_jql.","commonSituations":"UI/connector-pair config form submitted with neither field filled; YAML/JSON config where the key was misspelled (e.g. jql instead of jql_query) so the connector never received the value; programmatically building connectors from a template that lacks the selection field.","solutions":["Set exactly one of project_key (e.g. 'OPS') or jql_query (e.g. 'project = OPS AND updated >= -7d') in the connector config.","If you believe you set it, verify the exact key names the connector reads (jql_query, project_key) and that values are non-empty strings after config parsing.","Add an up-front assertion/validation at connector construction time so misconfiguration fails before any Jira network call."],"exampleFix":"# before\nconnector = JiraConnector(base_url=..., project_key=None, jql_query=None)\nconnector.load_from_checkpoint(start, end, checkpoint)  # raises ConnectorValidationError\n\n# after\nif not (jql_query or project_key):\n    raise ValueError(\"Configure either project_key or jql_query before creating the Jira connector\")\nconnector = JiraConnector(base_url=..., project_key=project_key, jql_query=jql_query)","handlingStrategy":"validation","validationCode":"if not (config.get(\"jql_query\") or config.get(\"project_key\")):\n    raise ValueError(\"Jira connector requires project_key or jql_query\")","typeGuard":"def has_jira_selection(cfg: dict) -> bool:\n    return bool(cfg.get(\"jql_query\") or cfg.get(\"project_key\"))","tryCatchPattern":null,"preventionTips":["Validate connector config at form/API submission time, before the connector is ever constructed.","Keep the canonical option names (project_key, jql_query) in one place to avoid misspelled keys."],"tags":["jira","configuration","validation","connector","jql"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}