pathwaycom/pathway · error · ValueError

The 'max_difference' can't be negative

Error message

The 'max_difference' can't be negative

What it means

ValueError raised when max_difference is an int but negative. max_difference bounds the tolerated time skew between synchronized sources, so negative values are meaningless.

Source

Thrown at python/pathway/io/_synchronization.py:244

    - However, if the second source instead sends a record with ``T + 5m``, this record \
      is processed normally. The system will continue waiting for the first source to \
      catch up before advancing further.

    This behavior ensures that data gaps do not cause deadlocks but are properly detected and handled.
    """

    if len(columns) < 2:
        raise ValueError("At least two columns must participate in a connector group")

    if not isinstance(max_difference, int) and not isinstance(
        max_difference, datetime.timedelta
    ):
        raise ValueError(
            "The 'max_difference' must either be an integer or a datetime.timedelta"
        )

    if isinstance(max_difference, int) and max_difference < 0:
        raise ValueError("The 'max_difference' can't be negative")
    if isinstance(
        max_difference, datetime.timedelta
    ) and max_difference < datetime.timedelta(0):
        raise ValueError("The 'max_difference' can't be negative")

    column_types = set()
    for synchronized_column in columns:
        if isinstance(synchronized_column, ColumnReference):
            column = synchronized_column
            priority = SynchronizedColumn.__dataclass_fields__["priority"].default
            idle_duration = None
        else:
            column = synchronized_column.column
            priority = synchronized_column.priority
            idle_duration = synchronized_column.idle_duration
            if idle_duration is not None:
                idle_duration = datetime.timedelta(
                    seconds=as_duration_seconds(idle_duration, "idle_duration")

View on GitHub (pinned to fa2f74a464)

Solutions

1. Use a non-negative int (0 is allowed): max_difference=600
2. Validate config values before building the pipeline: if md < 0: raise ...
3. If 0 was intended to mean 'no skew tolerance', confirm that is the desired behavior

Example fix

// before
pw.io.synchronize(a.time, b.time, max_difference=-600)

// after
pw.io.synchronize(a.time, b.time, max_difference=600)

def validate_max_difference(v) -> None:
    if isinstance(v, int) and not isinstance(v, bool) and v < 0:
        raise ValueError('max_difference (int seconds) cannot be negative')

When it happens

Trigger: sync(a.time, b.time, max_difference=-600); a computed int that underflows to negative; negated config value.

Common situations: Sign error in configuration; arithmetic on config (e.g. -window for reversed semantics); bad default in shared config.

Related errors

• The 'max_difference' must either be an integer or a datetime
• Only one column from a table can be used in a synchronizatio
• At least two columns must participate in a connector group
• Failed to find the column '{column._name}' in table {column.
• Failed to install dependencies

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/3b2c8ebcdb68b359. Report an issue: GitHub.