jax-ml/jax · error · ValueError

Factor names have to start with a letter, but got '{char}'

Error message

Factor names have to start with a letter, but got '{char}'

What it means

Factor names in the rule must start with a letter (subsequent characters may be letters, digits, or '_'). A digit encountered where a new factor name begins raises this error.

Source

Thrown at jax/_src/custom_partitioning_sharding_rule.py:299

        if current_compound_dim is not None:
          raise ValueError(
              "Compound factors should be one level, nested brackets are not"
              " allowed")
        current_compound_dim = []
      elif char == ")":
        if current_compound_dim is None:
          raise ValueError("Brackets are not balanced")
        if len(current_compound_dim) <= 1:
          raise ValueError("Brackets should contain at least two factors")
        value.append(CompoundFactor(*current_compound_dim))
        current_compound_dim = None
      elif char == ",":
        all_values.append(ArrayMapping(*value))
        value = []
    elif char == "_" or char.isdigit() or char.isalpha():
      if current_factor is None:
        if str.isdigit(char):
          raise ValueError(f"Factor names have to start with a letter, but got '{char}'")
        current_factor = char
      else:
        current_factor += char
    else:
      raise ValueError(f"Unknown character '{char}'")

  if current_compound_dim is not None:
    raise ValueError(f"Brackets are not balanced in rule: '{rule}'")
  if current_factor is not None:
    add_factor(current_factor)
  all_values.append(ArrayMapping(*value))

  return tuple(all_values)

def str_to_sdy_sharding_rule(rule: str, *,
                             reduction_factors: tuple[str, ...] = (),
                             need_replication_factors: tuple[str, ...] = (),
                             permutation_factors: tuple[str, ...] = (),

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Start factor names with a letter, e.g. 'd3' instead of '3d'
2. Move numeric sizes into factor_sizes, keeping symbolic names in the rule

Example fix

# before
rule = '3d,f->f'
# after
rule = 'd3,f->f'  # with factor_sizes={'d3': ...} if needed

import re
for tok in re.findall(r'[A-Za-z0-9_]+', rule):
    assert tok[0].isalpha(), f'factor name {tok!r} must start with a letter'

import re
def names_start_with_letter(rule: str) -> bool:
    return all(t[0].isalpha() for t in re.findall(r'[A-Za-z0-9_]+', rule) if t)

When it happens

Trigger: Rule token like '2i' or '4' standing alone, e.g. '2i,j->j'.

Common situations: Trying to encode numeric sizes directly in the rule instead of using symbolic factor names plus factor_sizes; names like '3d_weight'.

Related errors

• Compound factors should be one level, nested brackets are no
• Brackets are not balanced
• Brackets should contain at least two factors
• Brackets are not balanced in rule: '{rule}'
• rule must be a str, but got {type(rule)}

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