infiniflow/ragflow · error · ConnectorValidationError

Jira resource not found (HTTP 404).

Error message

Jira resource not found (HTTP 404).

What it means

ConnectorValidationError raised by _handle_validation_error when the Jira exception has status_code == 404. The endpoint or resource referenced does not exist at that base URL: wrong site or host, a deleted project, an unknown issue key in the JQL, or a rest_api_version whose routes the server does not expose.

Source

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

            )
            try:
                return (yield from self._load_from_checkpoint_internal(jql, checkpoint, start_filter=start))
            except Exception as exc:
                if attempt_start is not None and not retried_with_buffer and is_atlassian_date_error(exc):
                    attempt_start = attempt_start - ONE_HOUR
                    retried_with_buffer = True
                    logger.info(f"[Jira] Atlassian date error detected; retrying with start={attempt_start}.")
                    continue
                raise

    def _handle_validation_error(self, exc: Exception) -> None:
        status_code = getattr(exc, "status_code", None)
        if status_code == 401:
            raise InsufficientPermissionsError("Jira credential appears to be invalid or expired (HTTP 401).") from exc
        if status_code == 403:
            raise InsufficientPermissionsError("Jira token does not have permission to access the requested resources (HTTP 403).") from exc
        if status_code == 404:
            raise ConnectorValidationError("Jira resource not found (HTTP 404).") from exc
        if status_code == 429:
            raise ConnectorValidationError("Jira rate limit exceeded during validation (HTTP 429).") from exc

        message = getattr(exc, "text", str(exc))
        if not message:
            raise UnexpectedValidationError("Unexpected Jira validation error.") from exc

        raise ConnectorValidationError(f"Jira validation failed: {message}") from exc

    def _load_from_checkpoint_internal(
        self,
        jql: str,
        checkpoint: JiraCheckpoint,
        start_filter: SecondsSinceUnixEpoch | None = None,
    ) -> Generator[Document | ConnectorFailure, None, JiraCheckpoint]:
        assert self.jira_client, "load_credentials must be called before loading issues."

        page_size = self._full_page_size()

View on GitHub (pinned to 554fb1133a)

Solutions

1. Verify the project key exists: browse https://yourcompany.atlassian.net/browse/KEY or call /rest/api/3/project/KEY.
2. Correct jira_base_url if the site changed, and update project_key/jql_query for renamed or archived projects.
3. Unset a forced rest_api_version so the client negotiates the right API for the server type.
4. Check __cause__ for which URL 404'd.

Example fix

# before
connector = JiraConnector(jira_base_url='https://acme.atlassian.net', project_key='OLDKEY')  # archived -> 404

# after
connector = JiraConnector(jira_base_url='https://acme.atlassian.net', project_key='NEWKEY')

def jira_project_exists(base_url: str, token: str, project_key: str) -> bool:
    import requests
    r = requests.get(f'{base_url.rstrip("/")}/rest/api/3/project/{project_key}',
                     headers={'Authorization': f'Bearer {token}'}, timeout=10)
    return r.status_code != 404

try:
    connector.validate_connector_settings()
except ConnectorValidationError as e:
    if 'HTTP 404' in str(e):
        raise ValueError('Jira project or site not found; verify base URL and project key') from e
    raise

When it happens

Trigger: validate_connector_settings() with a jql_query naming a deleted or nonexistent project (or issue key); the base URL pointing to a different site than the one hosting the project; a Jira Server vs Cloud API shape mismatch via rest_api_version.

Common situations: Renamed or archived projects after the connector was configured; a typo'd project_key; a tenant moved to another Atlassian site; migration between Server and Cloud.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

• Jira base URL must be provided.
• Invalid time_buffer_seconds value ({time_buffer_seconds!r});
• Either project_key or jql_query must be provided for Jira co
• main() returned a non-JSON-serializable value.
• main() must return a value. Use null for an empty result.

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