infiniflow/ragflow · error · ConnectorValidationError

Either project_key or jql_query must be provided for Jira co

Error message

Either project_key or jql_query must be provided for Jira connector.

What it means

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.

Source

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

                page_size=_JIRA_SLIM_PAGE_SIZE,
            )
            prev_offset = current_offset

        if slim_batch:
            yield slim_batch

    # -------------------------------------------------------------------------
    # Internal helpers
    # -------------------------------------------------------------------------

    def _build_jql(self, start: SecondsSinceUnixEpoch, end: SecondsSinceUnixEpoch) -> str:
        clauses: list[str] = []
        if self.jql_query:
            clauses.append(f"({self.jql_query})")
        elif self.project_key:
            clauses.append(f'project = "{self.project_key}"')
        else:
            raise ConnectorValidationError("Either project_key or jql_query must be provided for Jira connector.")

        if self.labels_to_skip:
            labels = ", ".join(f'"{label}"' for label in self.labels_to_skip)
            clauses.append(f"labels NOT IN ({labels})")

        adjusted_start = self._adjust_start_for_query(start)
        if adjusted_start is not None:
            clauses.append(f'updated >= "{self._format_jql_time(adjusted_start)}"')
        if end is not None:
            clauses.append(f'updated <= "{self._format_jql_time(end)}"')

        if not clauses:
            raise ConnectorValidationError("Unable to build Jira JQL query.")

        jql = " AND ".join(clauses)
        if "order by" not in jql.lower():
            jql = f"{jql} ORDER BY updated ASC"
        return jql

View on GitHub (pinned to 554fb1133a)

Solutions

1. Set exactly one of project_key (e.g. 'OPS') or jql_query (e.g. 'project = OPS AND updated >= -7d') in the connector config.
2. 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.
3. Add an up-front assertion/validation at connector construction time so misconfiguration fails before any Jira network call.

Example fix

# before
connector = JiraConnector(base_url=..., project_key=None, jql_query=None)
connector.load_from_checkpoint(start, end, checkpoint)  # raises ConnectorValidationError

# after
if not (jql_query or project_key):
    raise ValueError("Configure either project_key or jql_query before creating the Jira connector")
connector = JiraConnector(base_url=..., project_key=project_key, jql_query=jql_query)

if not (config.get("jql_query") or config.get("project_key")):
    raise ValueError("Jira connector requires project_key or jql_query")

def has_jira_selection(cfg: dict) -> bool:
    return bool(cfg.get("jql_query") or cfg.get("project_key"))

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Jira base URL must be provided.
• main() must return a value. Use null for an empty result.
• BigQuery requires either a custom query or both dataset_id a
• Invalid time_buffer_seconds value ({time_buffer_seconds!r});
• Jira resource not found (HTTP 404).

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