infiniflow/ragflow · error · ConnectorValidationError

Jira base URL must be provided.

Error message

Jira base URL must be provided.

What it means

ConnectorValidationError raised in the JiraConnector constructor when jira_base_url is None or empty. The base URL is the only strictly required constructor argument; everything else has defaults. It fails at construction time, before any credential loading or network calls.

Source

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

    """Retrieve Jira issues and emit them as Markdown documents."""

    def __init__(
        self,
        jira_base_url: str,
        project_key: str | None = None,
        jql_query: str | None = None,
        batch_size: int = INDEX_BATCH_SIZE,
        include_comments: bool = True,
        include_attachments: bool = False,
        labels_to_skip: Sequence[str] | None = None,
        comment_email_blacklist: Sequence[str] | None = None,
        scoped_token: bool = False,
        attachment_size_limit: int | None = None,
        timezone_offset: float | None = None,
        time_buffer_seconds: int | None = JIRA_SYNC_TIME_BUFFER_SECONDS,
    ) -> None:
        if not jira_base_url:
            raise ConnectorValidationError("Jira base URL must be provided.")

        self.jira_base_url = jira_base_url.rstrip("/")
        self.project_key = project_key
        self.jql_query = jql_query
        self.batch_size = batch_size
        self.include_comments = include_comments
        self.include_attachments = include_attachments
        configured_labels = labels_to_skip or JIRA_CONNECTOR_LABELS_TO_SKIP
        self.labels_to_skip = {label.lower() for label in configured_labels}
        self.comment_email_blacklist = {email.lower() for email in comment_email_blacklist or []}
        self.scoped_token = scoped_token
        self.jira_client: JIRA | None = None

        self.max_ticket_size = JIRA_CONNECTOR_MAX_TICKET_SIZE
        self.attachment_size_limit = attachment_size_limit if attachment_size_limit and attachment_size_limit > 0 else _DEFAULT_ATTACHMENT_SIZE_LIMIT
        self._fields_param = _DEFAULT_FIELDS
        self._slim_fields = _SLIM_FIELDS

View on GitHub (pinned to 554fb1133a)

Solutions

1. Supply a non-empty base URL, e.g. 'https://yourcompany.atlassian.net' (Atlassian Cloud) or your Jira Server origin.
2. Validate the config source before construction: fail fast with a clear message when the field is blank.
3. Check for trailing whitespace or a value of the literal string 'None' coming from env vars.

Example fix

# before
connector = JiraConnector(jira_base_url=cfg.get('jira_url', ''), project_key='OPS')  # '' -> ValidationError

# after
url = (cfg.get('jira_url') or '').strip()
if not url:
    raise SystemExit('jira_url is required')
connector = JiraConnector(jira_base_url=url, project_key='OPS')

def valid_jira_base_url(url) -> bool:
    return isinstance(url, str) and bool(url.strip()) and url.strip().startswith(('http://', 'https://'))

try:
    connector = JiraConnector(jira_base_url=base_url, project_key=key)
except ConnectorValidationError as e:
    if 'base URL must be provided' in str(e):
        raise ValueError('Config source is missing the Jira URL field') from e
    raise

When it happens

Trigger: Instantiating JiraConnector(jira_base_url='') or JiraConnector(jira_base_url=None, project_key='X'); passing a config dict where the URL key is misspelled or the value was consumed by an earlier .pop() or defaulted .get().

Common situations: Building connectors from tenant config where the URL field is blank in the UI; YAML/env misalignment (JIRA_URL vs JIRA_BASE_URL); a migration script creating connectors in bulk and skipping rows without a URL.

Related errors

• Either project_key or jql_query must be provided for Jira co
• 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/b1791637a6bf7461. Report an issue: GitHub.