jax-ml/jax · error · ValueError

A compound factor should contain at least two factors

Error message

A compound factor should contain at least two factors

What it means

CompoundFactor groups multiple factors that must all be matched along a single dimension; it requires at least two factors. Constructing CompoundFactor with fewer raises ValueError.

Source

Thrown at jax/_src/custom_partitioning_sharding_rule.py:65

     optionally followed by a digit, and ... is equivalent to ...0.
  """
  if len(factor) < 1 or factor[0] != BATCHING:
    return False
  return len(factor) == 1 or factor[1:].isdigit()

def _get_batching_group(factor: str) -> str:
  """Extracts the batching group from a factor for leading batching dimensions."""
  return factor[1:] if len(factor) > 1 else "0"

class CompoundFactor(tuple):
  """Describes the factors for a compound factor.

  A compound factor should contain at least two factors, e.g.
  * CompoundFactor('b', 'c').
  """
  def __init__(self, *factors):
    if len(factors) < 2:
      raise ValueError("A compound factor should contain at least two factors")
    for factor in factors:
      if not isinstance(factor, str):
        raise ValueError(f"Each element of CompoundFactor must be a str, but got {type(factor)}")
      if _is_batching(factor):
        raise ValueError("Ellipsis can't be used in a compound factor")
      else:
        _check_factor(factor)

  def __new__(cls, *factors):
    return tuple.__new__(CompoundFactor, factors)


class ArrayMapping(tuple):
  """Describes the factors for an operand or result.

  Each element is either a factor or a CompoundFactor. A leading element can
  also be BATCHING, which represents batching dimensions. examples:
  * ArrayMapping('a')

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Pass at least two factors, e.g. CompoundFactor('b', 'c')
2. If only one factor applies, use the plain string 'b' instead of CompoundFactor
3. Guard generated rule builders against singleton lists

Example fix

# before
CompoundFactor('b')

# after
'b'  # single factor needs no CompoundFactor

assert len(factors) >= 2, 'CompoundFactor needs >= 2 factors'
CompoundFactor(*factors) if len(factors) >= 2 else factors[0]

When it happens

Trigger: Calling CompoundFactor('b') (one factor) or CompoundFactor() (none) while building an SdyShardingRule mapping.

Common situations: Programmatic rule generation that loops over factor lists and can emit a singleton compound factor.

Related errors

• Factor names have to start with a letter, but got '{factor[0
• Unknown character '{char}'
• Unknown keyword arguments: {sharding_rule_dict}
• sharding_rule callable must produce either an SdyShardingRul
• Each element of CompoundFactor must be a str, but got {type(

AI-assisted analysis of jax-ml/jax@1e1c6a8fc0 (2026-08-27). Data as JSON: /api/errors/6d696e1341a11b51. Report an issue: GitHub.