infiniflow/ragflow · error · ConnectorValidationError

Invalid time_buffer_seconds value ({time_buffer_seconds!r});

Error message

Invalid time_buffer_seconds value ({time_buffer_seconds!r}); expected an integer.

What it means

ConnectorValidationError raised when the optional time_buffer_seconds constructor argument cannot be converted with int() - i.e. it is a non-numeric string like '90s', a float such as 1.5, or a type like a list or dict. None is allowed (falls back to JIRA_SYNC_TIME_BUFFER_SECONDS); valid ints and int-strings are accepted.

Source

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

        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

        tz_offset_value = float(timezone_offset) if timezone_offset is not None else float(JIRA_TIMEZONE_OFFSET)
        self.timezone_offset = tz_offset_value
        self.timezone = timezone(offset=timedelta(hours=tz_offset_value))
        self._timezone_overridden = timezone_offset is not None
        if time_buffer_seconds is None:
            buffer_value = JIRA_SYNC_TIME_BUFFER_SECONDS
        else:
            try:
                buffer_value = int(time_buffer_seconds)
            except (TypeError, ValueError) as exc:
                raise ConnectorValidationError(f"Invalid time_buffer_seconds value ({time_buffer_seconds!r}); expected an integer.") from exc
        self.time_buffer_seconds = max(0, buffer_value)

    # -------------------------------------------------------------------------
    # Connector lifecycle helpers
    # -------------------------------------------------------------------------

    def load_credentials(self, credentials: dict[str, Any]) -> dict[str, Any] | None:
        """Instantiate the Jira client using either an API token or username/password."""
        jira_url_for_client = self.jira_base_url
        if self.scoped_token:
            if is_atlassian_cloud_url(self.jira_base_url):
                try:
                    jira_url_for_client = scoped_url(self.jira_base_url, "jira")
                except ValueError as exc:
                    raise ConnectorValidationError(str(exc)) from exc
            else:
                logger.warning("[Jira] Scoped token requested but Jira base URL does not appear to be an Atlassian Cloud domain; scoped token ignored.")

View on GitHub (pinned to 554fb1133a)

Solutions

Pass a plain integer or an integer string: time_buffer_seconds=3600 or '3600'.
If the config may hold units or floats, normalize before construction: int(float(value)) after stripping units.
Add schema validation (e.g. a pydantic int type) on the config layer that feeds the connector.

Example fix

# before
connector = JiraConnector(jira_base_url=url, time_buffer_seconds='30s')  # ValueError

# after
connector = JiraConnector(jira_base_url=url, time_buffer_seconds=30)

Defensive patterns

Strategy: validation

Validate before calling

def valid_time_buffer_seconds(value) -> bool:
    if value is None:
        return True
    if isinstance(value, bool):
        return False
    try:
        int(value)
        return True
    except (TypeError, ValueError):
        return False

Type guard

def is_int_coercible(value) -> bool:
    if isinstance(value, bool):
        return False
    try:
        int(value)
        return True
    except (TypeError, ValueError):
        return False

Try / catch

try:
    connector = JiraConnector(jira_base_url=url, time_buffer_seconds=buffer_cfg)
except ConnectorValidationError as e:
    if 'time_buffer_seconds' in str(e):
        connector = JiraConnector(jira_base_url=url)  # fall back to the default buffer
    else:
        raise

Prevention

Declare numeric config fields as int in the schema layer, not free-form strings.
Reject values with unit suffixes at config parse time.
When None is acceptable, pass None explicitly rather than an empty string.

When it happens

Trigger: Passing time_buffer_seconds='30s' or 1.5, or a value read from an env var/config without prior numeric validation. int('1.5') and int([1]) raise TypeError/ValueError, both caught and re-raised as this validation error.

Common situations: Config values authored as strings with units ('30s') by analogy with other settings; env vars parsed as strings; UI numeric inputs not validated before reaching the connector.

Related errors

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