pathwaycom/pathway · error · ValueError

At least two columns must participate in a connector group

Error message

At least two columns must participate in a connector group

What it means

ValueError raised by the connector synchronization API (pathway.io.synchronize / the sync() function in _synchronization.py) when fewer than two columns are passed. A synchronization group by definition coordinates at least two data sources, so a single column is rejected.

Source

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

    **Example scenario:**
    Consider a synchronization group with two data sources, both tracking a ``timestamp``
    column, and ``max_difference`` set to 600 seconds (10 minutes).

    - Initially, both sources send a record with timestamp ``T``.
    - Later, the first source sends a record with ``T + 1h``. \
      This record is not yet forwarded for processing because it exceeds ``max_difference``.
    - If the second source then sends a record with ``T + 1h``, the system detects a 1-hour gap. \
      Since both sources have moved beyond ``T``, the synchronization group accepts ``T + 1h`` \
      as the new baseline and continues processing from there.
    - 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):

View on GitHub (pinned to fa2f74a464)

Solutions

1. Provide at least two columns from at least two different input tables: sync(t1.time, t2.time, max_difference=600)
2. If you only have one source, remove the synchronization group entirely
3. Wrap bare columns in pw.io.SynchronizedColumn when you also need priority/idle_duration, keeping at least two entries

Example fix

// before
pw.io.synchronize(transactions.time, max_difference=600)

// after
pw.io.synchronize(transactions.time, login_events.time, max_difference=600)

def validate_sync_columns(columns) -> None:
    if len(columns) < 2:
        raise ValueError('synchronization group needs >= 2 columns from different tables')

When it happens

Trigger: Calling the sync/synchronize API with a single column: sync(transactions.time, max_difference=600); passing an empty columns list; passing one ColumnReference where two SynchronizedColumn entries were intended.

Common situations: Adding a second source incrementally and testing with one first; refactoring that drops a column argument; misunderstanding that synchronization coordinates sources against each other, not against wall-clock time.

Related errors

• Only one column from a table can be used in a synchronizatio
• synchronization_group can only be set once
• The 'max_difference' must either be an integer or a datetime
• The 'max_difference' can't be negative
• Failed to find the column '{column._name}' in table {column.

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