{"record":{"id":"3f366f7ac25c3786","repo":"apache/beam","slug":"integer-value-value-is-out-of-the-encodable-range-for","errorCode":null,"errorMessage":"Integer value '{value}' is out of the encodable range for VarIntCoder. This coder is limited to values that fit within a 64-bit signed integer (-(2**63) to 2**63 - 1). Original error: {e}","messagePattern":"Integer value '(.+?)' is out of the encodable range for VarIntCoder\\. This coder is limited to values that fit within a 64-bit signed integer \\(-\\(2\\*\\*63\\) to 2\\*\\*63 - 1\\)\\. Original error: (.+?)","errorType":"exception","errorClass":"OverflowError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/coders/coder_impl.py","lineNumber":1049,"sourceCode":"            in_stream, True),\n        hold_timestamp=self._timestamp_coder_impl.decode_from_stream(\n            in_stream, True),\n        paneinfo=self._pane_info_coder_impl.decode_from_stream(in_stream, True))\n\n\nsmall_ints = [chr(_).encode('latin-1') for _ in range(128)]\n\n\nclass VarIntCoderImpl(StreamCoderImpl):\n  \"\"\"For internal use only; no backwards-compatibility guarantees.\n\n  A coder for int objects.\"\"\"\n  def encode_to_stream(self, value, out, nested):\n    # type: (int, create_OutputStream, bool) -> None\n    try:\n      out.write_var_int64(value)\n    except OverflowError as e:\n      raise OverflowError(\n          f\"Integer value '{value}' is out of the encodable range for \"\n          f\"VarIntCoder. This coder is limited to values that fit \"\n          f\"within a 64-bit signed integer (-(2**63) to 2**63 - 1). \"\n          f\"Original error: {e}\") from e\n\n  def decode_from_stream(self, in_stream, nested):\n    # type: (create_InputStream, bool) -> int\n    return in_stream.read_var_int64()\n\n  def encode(self, value):\n    ivalue = value  # type cast\n    if 0 <= ivalue < len(small_ints):\n      return small_ints[ivalue]\n    return StreamCoderImpl.encode(self, value)\n\n  def decode(self, encoded):\n    if len(encoded) == 1:\n      i = ord(encoded)","sourceCodeStart":1031,"sourceCodeEnd":1067,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/coders/coder_impl.py#L1031-L1067","documentation":"VarIntCoderImpl.encode_to_stream calls out.write_var_int64, which only accepts 64-bit signed integers. If the value overflows that range, OverflowError is re-raised with a message naming the offending value and the allowed range -(2**63) to 2**63-1. Beam raises this so callers know the value simply cannot be represented by VarIntCoder.","triggerScenarios":"Calling VarIntCoder().encode(value) (or a pipeline coding a PCollection of ints) where value >= 2**63 or value < -(2**63), e.g. huge counters, timestamps in nanoseconds since epoch far in the future, or unbounded arithmetic results.","commonSituations":"Computing timestamps/durations in nanoseconds with int64 overflow; aggregating counts that exceed 2**63; using Python's arbitrary-precision ints from user data without range validation before coding.","solutions":["Clamp or validate values to the 64-bit signed range before coding","Use a different representation for huge numbers (e.g., encode as a string or bytes via a custom/Map coder)","Scale units down (e.g., nanoseconds to milliseconds) so values fit in int64","Fix upstream arithmetic (use modular arithmetic or floats) so intermediate results stay in range"],"exampleFix":"// before\ncoder = VarIntCoder()\ncoder.encode(huge_ns_timestamp)  # OverflowError\n// after\nINT64_MIN, INT64_MAX = -(2**63), 2**63 - 1\nif not (INT64_MIN <= value <= INT64_MAX):\n    value = value // 1000  # rescale ns -> us\ncoder.encode(value)","handlingStrategy":"validation","validationCode":"INT64_MIN, INT64_MAX = -(2**63), 2**63 - 1\nassert INT64_MIN <= value <= INT64_MAX, f'value {value} not encodable by VarIntCoder'","typeGuard":"def fits_int64(v: int) -> bool:\n    return -(2**63) <= v <= 2**63 - 1","tryCatchPattern":"try:\n    coder.encode(value)\nexcept OverflowError as e:\n    log.warning('VarInt overflow: %s', e)\n    value = rescale_or_clamp(value)\n    coder.encode(value)","preventionTips":["Validate int64 bounds at pipeline boundaries before coding","Prefer smaller time units (ms/us) over nanoseconds for int64-coded timestamps","Guard aggregations (sums/counters) that could exceed 2**63"],"tags":["python","apache-beam","coding","integer-overflow"],"backgroundTag":"value-out-of-range","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}