{"record":{"id":"2eb7945b7ed55a67","repo":"apache/beam","slug":"parameter-for-a-zipf-distribution-must-be-larger-than-1","errorCode":null,"errorMessage":"Parameter for a Zipf distribution must be larger than 1. Received %r.","messagePattern":"Parameter for a Zipf distribution must be larger than 1\\. Received %r\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/testing/synthetic_pipeline.py","lineNumber":372,"sourceCode":"    self._value_size = maybe_parse_byte_size(\n        input_spec.get('valueSizeBytes', 1))\n    self._total_size = self.element_size * self._num_records\n    self._initial_splitting = (\n        input_spec['bundleSizeDistribution']['type']\n        if 'bundleSizeDistribution' in input_spec else 'const')\n    if self._initial_splitting != 'const' and self._initial_splitting != 'zipf':\n      raise ValueError(\n          'Only const and zipf distributions are supported for determining '\n          'sizes of bundles produced by initial splitting. Received: %s',\n          self._initial_splitting)\n    self._initial_splitting_num_bundles = (\n        input_spec['forceNumInitialBundles']\n        if 'forceNumInitialBundles' in input_spec else 0)\n    if self._initial_splitting == 'zipf':\n      self._initial_splitting_distribution_parameter = (\n          input_spec['bundleSizeDistribution']['param'])\n      if self._initial_splitting_distribution_parameter < 1:\n        raise ValueError(\n            'Parameter for a Zipf distribution must be larger than 1. '\n            'Received %r.',\n            self._initial_splitting_distribution_parameter)\n    else:\n      self._initial_splitting_distribution_parameter = 0\n    self._dynamic_splitting = (\n        'none' if (\n            'splitPointFrequencyRecords' in input_spec and\n            input_spec['splitPointFrequencyRecords'] == 0) else 'perfect')\n    if 'delayDistribution' in input_spec:\n      if input_spec['delayDistribution']['type'] != 'const':\n        raise ValueError(\n            'SyntheticSource currently only supports delay '\n            'distributions of type \\'const\\'. Received %s.',\n            input_spec['delayDistribution']['type'])\n      self._sleep_per_input_record_sec = (\n          float(input_spec['delayDistribution']['const']) / 1000)\n      if (self._sleep_per_input_record_sec and","sourceCodeStart":354,"sourceCodeEnd":390,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/testing/synthetic_pipeline.py#L354-L390","documentation":"SyntheticSource's __init__ validates the bundle-size distribution parameter when initial splitting is set to 'zipf'. A Zipf distribution is only mathematically defined for a parameter strictly greater than 1, so the source raises ValueError when the configured param is <= 1. Note the check uses < 1, so exactly 1 also passes but is still invalid for a true Zipf law; any value below 1 is rejected.","triggerScenarios":"Constructing a SyntheticSource (or running a synthetic pipeline) with input_spec['initialSplitting'] == 'zipf' and input_spec['bundleSizeDistribution'] == {'type': 'zipf', 'param': 1} or any param less than 1 (e.g. 0.5, 0, -3).","commonSituations":"Hand-editing synthetic pipeline config JSON for load-testing Beam runners; copying a uniform-distribution config and only changing the type to 'zipf' without adjusting param; param mistakenly given as a percentage (0.9) instead of the Zipf exponent.","solutions":["Set input_spec['bundleSizeDistribution']['param'] to a value strictly greater than 1 (e.g. 1.5 or 2.0).","If you do not specifically need Zipf, switch initial splitting to 'uniform' (the parameter is then ignored).","Validate the config JSON before launching the pipeline (check type=='zipf' implies param > 1)."],"exampleFix":"// before\ninput_spec = {'initialSplitting': 'zipf', 'bundleSizeDistribution': {'type': 'zipf', 'param': 1}}\n// after\ninput_spec = {'initialSplitting': 'zipf', 'bundleSizeDistribution': {'type': 'zipf', 'param': 2.0}}","handlingStrategy":"validation","validationCode":"dist = input_spec.get('bundleSizeDistribution', {})\nif input_spec.get('initialSplitting') == 'zipf' and not (isinstance(dist.get('param'), (int, float)) and dist.get('param', 0) > 1):\n    raise ValueError('zipf param must be > 1')","typeGuard":"def is_valid_zipf_param(v) -> bool:\n    return isinstance(v, (int, float)) and v > 1","tryCatchPattern":"try:\n    source = SyntheticStep(input_spec, ...)\nexcept ValueError as e:\n    if 'Zipf distribution' in str(e):\n        input_spec['bundleSizeDistribution']['param'] = 2.0\n        source = SyntheticStep(input_spec, ...)\n    else:\n        raise","preventionTips":["Keep a JSON schema for synthetic pipeline input_spec and validate before launch","Use param values like 1.0 < p <= 3 typical for Zipf workloads","Add a unit test covering each initialSplitting/bundleSizeDistribution combination"],"tags":["python","apache-beam","valueerror","synthetic-pipeline","configuration"],"backgroundTag":"invalid-config-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}