jax-ml/jax · error · ValueError

Each element of CompoundFactor must be a str, but got

Error message

Each element of CompoundFactor must be a str, but got {type(factor)}

What it means

CompoundFactor members must be plain factor strings; the constructor rejects elements of any other type (e.g. a nested CompoundFactor or an int) because the rule parser only emits and consumes string factors.

Solutions

1. Convert elements to strings before constructing: CompoundFactor(str(f1), str(f2))
2. Flatten nested CompoundFactors into their string components
3. Add a type check in rule-generation code

Example fix

# before
CompoundFactor(mesh_axis_id, 'c')  # int

# after
CompoundFactor(str(mesh_axis_id), 'c')

assert all(isinstance(f, str) for f in factors), [type(f) for f in factors]

def all_str(factors):
    return all(isinstance(f, str) for f in factors)

When it happens

Trigger: CompoundFactor(2, 'c'), CompoundFactor(['b'], 'c'), or nested CompoundFactor usage while building sharding rules.

Common situations: Building rules programmatically where factor lists may contain ints or nested tuples.

Related errors

• Each element of ArrayMapping must be a str or…
• A compound factor should contain at least two factors
• Ellipsis can only be used at the beginning of a dimension
• Ellipsis can't be used in a compound factor
• Factor names have to start with a letter, but got

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

Appendix: source

Thrown at jax/_src/custom_partitioning_sharding_rule.py:68

    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')
  * ArrayMapping('b', 'c')
  * ArrayMapping(CompoundFactor('b', 'c'), 'd')
  * ArrayMapping(BATCHING, CompoundFactor('b', 'c'), 'd')

View on GitHub (pinned to 1e1c6a8fc0)