{"record":{"id":"ff8ac4a2f7a9a47d","repo":"pathwaycom/pathway","slug":"the-max-difference-must-either-be-an-integer-or","errorCode":null,"errorMessage":"The 'max_difference' must either be an integer or a datetime.timedelta","messagePattern":"The 'max_difference' must either be an integer or a datetime\\.timedelta","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/pathway/io/_synchronization.py","lineNumber":239,"sourceCode":"    - Later, the first source sends a record with ``T + 1h``. \\\n      This record is not yet forwarded for processing because it exceeds ``max_difference``.\n    - If the second source then sends a record with ``T + 1h``, the system detects a 1-hour gap. \\\n      Since both sources have moved beyond ``T``, the synchronization group accepts ``T + 1h`` \\\n      as the new baseline and continues processing from there.\n    - However, if the second source instead sends a record with ``T + 5m``, this record \\\n      is processed normally. The system will continue waiting for the first source to \\\n      catch up before advancing further.\n\n    This behavior ensures that data gaps do not cause deadlocks but are properly detected and handled.\n    \"\"\"\n\n    if len(columns) < 2:\n        raise ValueError(\"At least two columns must participate in a connector group\")\n\n    if not isinstance(max_difference, int) and not isinstance(\n        max_difference, datetime.timedelta\n    ):\n        raise ValueError(\n            \"The 'max_difference' must either be an integer or a datetime.timedelta\"\n        )\n\n    if isinstance(max_difference, int) and max_difference < 0:\n        raise ValueError(\"The 'max_difference' can't be negative\")\n    if isinstance(\n        max_difference, datetime.timedelta\n    ) and max_difference < datetime.timedelta(0):\n        raise ValueError(\"The 'max_difference' can't be negative\")\n\n    column_types = set()\n    for synchronized_column in columns:\n        if isinstance(synchronized_column, ColumnReference):\n            column = synchronized_column\n            priority = SynchronizedColumn.__dataclass_fields__[\"priority\"].default\n            idle_duration = None\n        else:\n            column = synchronized_column.column","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/pathwaycom/pathway/blob/fa2f74a4649b7c5908690cf60137263d8d80de5f/python/pathway/io/_synchronization.py#L221-L257","documentation":"ValueError raised by the connector synchronization API when max_difference is neither an int nor a datetime.timedelta. Ints are interpreted as seconds; timedeltas express the allowed inter-source time skew directly.","triggerScenarios":"Passing max_difference='600' (string), 600.0 (float), pandas.Timedelta, or datetime.datetime to the sync/synchronize function. Note: bool is technically an int subclass but a float seconds value is rejected.","commonSituations":"Reading max_difference from YAML/env as a string; using pandas.Timedelta from a config library; passing milliseconds as float; copy-pasting a timedelta expression that yields a Date.","solutions":["Use an int (seconds): max_difference=600","Or a datetime.timedelta: max_difference=datetime.timedelta(minutes=10)","Coerce config values before calling: int(cfg['max_difference']) or datetime.timedelta(seconds=float(cfg['max_difference']))"],"exampleFix":"// before\npw.io.synchronize(a.time, b.time, max_difference='600')\n\n// after\npw.io.synchronize(a.time, b.time, max_difference=600)  # or datetime.timedelta(seconds=600)","handlingStrategy":"validation","validationCode":"import datetime\n\ndef coerce_max_difference(v):\n    if isinstance(v, datetime.timedelta):\n        return v\n    if isinstance(v, int) and not isinstance(v, bool):\n        return v\n    if isinstance(v, str):\n        return int(v)  # or raise, per project policy\n    raise TypeError('max_difference must be int seconds or datetime.timedelta')","typeGuard":"import datetime\n\ndef is_valid_max_difference(v) -> bool:\n    return isinstance(v, int) and not isinstance(v, bool) or isinstance(v, datetime.timedelta)","tryCatchPattern":null,"preventionTips":["Normalize max_difference to int seconds or timedelta at config load time","Never pass strings or floats straight from YAML/env into the sync API","Unit-test config parsing for synchronization parameters"],"tags":["pathway","io","synchronization","validation"],"backgroundTag":null,"analyzedSha":"fa2f74a4649b7c5908690cf60137263d8d80de5f","analyzedAt":"2026-08-15T01:48:17.006Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}