{"record":{"id":"06c635202c944622","repo":"jax-ml/jax","slug":"factor-factor-is-only-used-in-compound-factors","errorCode":null,"errorMessage":"Factor {factor} is only used in compound factors; must specify its size","messagePattern":"Factor (.+?) is only used in compound factors; must specify its size","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/custom_partitioning_sharding_rule.py","lineNumber":152,"sourceCode":"        if isinstance(dim, str):\n          factors_inferrable[dim] = True\n        else:\n          for factor in dim:\n            if factor not in factors_inferrable.keys():\n              factors_inferrable[factor] = False\n\n    # Check that factors in factor_sizes are used in the rule.\n    for factor in factor_sizes:\n      if factor not in factors_inferrable:\n        raise ValueError(\n          f\"Factor {factor} is not used in the rule, but size is provided\")\n\n    # Check that factors that are used for a whole dimension aren't in\n    # factor_sizes and factors that are never used for a whole dimension are\n    # in factor_sizes.\n    for factor, inferable in factors_inferrable.items():\n      if factor not in factor_sizes and not inferable:\n        raise ValueError(\n          f\"Factor {factor} is only used in compound factors; must specify\"\n          \" its size\")\n      if factor in factor_sizes and inferable:\n        raise ValueError(\n          f\"Factor {factor} represents a whole dimension; do not specify its\"\n          \" size\")\n\n    special_factors = set()\n    def check_special_factors(kind, factors):\n      if not isinstance(factors, tuple):\n        raise ValueError(f\"{kind} must be a tuple of factors\")\n\n      if len(factors) != len(set(factors)):\n        raise ValueError(f\"{kind} contains duplicated factors\")\n\n      for factor in factors:\n        if factor not in factors_inferrable:\n          raise ValueError(","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/custom_partitioning_sharding_rule.py#L134-L170","documentation":"The factor appears in the rule only inside compound factors (e.g. '(a,b)'), so its size cannot be inferred from a dimension extent and must be given explicitly in factor_sizes. __init__ raises when such a factor is missing from factor_sizes.","triggerScenarios":"Rule like 'i,(a,b)->i' where 'a' and 'b' only occur inside parentheses, and factor_sizes omits 'a' or 'b'.","commonSituations":"Assuming all factors are inferable from dimension sizes; adding a compound factor to a rule without updating factor_sizes.","solutions":["Add the missing factor(s) to factor_sizes with explicit integer sizes, e.g. factor_sizes={'a':2,'b':4}","If the factor should span a whole dimension, move it out of the compound factor so it maps to a dimension directly"],"exampleFix":"# before\nrule = 'i,(a,b)->i'  # factor_sizes omitted\n# after\nrule = 'i,(a,b)->i'\nfactor_sizes = {'a': 2, 'b': 4}","handlingStrategy":"validation","validationCode":"import re\nwhole = re.findall(r'(?:^|[, (])([A-Za-z_][A-Za-z0-9_]*)(?=$|[,)])', rule.replace('->', ','))\ncompound_only = set(re.findall(r'[A-Za-z_][A-Za-z0-9_]*', rule)) - set(whole)\nmissing = compound_only - set(factor_sizes)\nassert not missing, f'must specify sizes for {missing}'","typeGuard":"def compound_factors_sized(rule: str, factor_sizes: dict[str, int]) -> bool:\n    return not missing if not (missing := _compound_only(rule) - set(factor_sizes)) else False","tryCatchPattern":null,"preventionTips":["Any factor appearing only inside parentheses needs an explicit size","Keep factor_sizes and rule in one config structure so they change together"],"tags":["jax","sharding","compound-factor","factor-sizes"],"backgroundTag":"missing-required-parameter","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}