jax-ml/jax · error · ValueError

Factor names have to start with a letter, but got '{factor[0

Error message

Factor names have to start with a letter, but got '{factor[0]}'

What it means

Factor names in SdyShardingRule / ArrayMapping notation must start with an ASCII letter. This ValueError is raised when a factor string begins with a digit, underscore, or symbol.

Source

Thrown at jax/_src/custom_partitioning_sharding_rule.py:38

from jax._src.lib.mlir.dialects import sdy


# A single character replacement for ... to simplify parsing.
BATCHING: str = "…"

# A prefix for names of batching dimension factors, used for expanding the
# leading ... into factors.
_BATCHING_DIM_FACTOR_PREFIX = "?"


def _check_factor(factor:str):
  """Validates a factor.

  A factor is a string starting with a letter and containing only letters,
  digits, or underscores.
  """
  if not factor[0].isalpha():
    raise ValueError(f"Factor names have to start with a letter, but got '{factor[0]}'")
  for char in factor[1:]:
    if char != "_" and not char.isdigit() and not char.isalpha():
      raise ValueError(f"Unknown character '{char}'")

def _is_batching(factor: str) -> bool:
  """Checks if a factor is a representation for leading batching dimensions.

  Leading batching dimensions is represented by a factor containing ... and
     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"

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Rename the factor to start with a letter, e.g. 'd0' instead of '0'
2. Check the rule string for stray symbols adjacent to factor tokens
3. Use descriptive factor names matching mesh axes

Example fix

# before
rule = SdyShardingRule((ArrayMapping('0', 'i'), ArrayMapping('i', '0')), ...)

# after
rule = SdyShardingRule((ArrayMapping('d0', 'i'), ArrayMapping('i', 'd0')), ...)

import re
FACTOR = re.compile(r'^[A-Za-z][A-Za-z0-9_]*$')
def check_factor(f): assert FACTOR.match(f), f

def valid_factor(f: str) -> bool:
    return bool(re.match(r'^[A-Za-z][A-Za-z0-9_]*$', f))

When it happens

Trigger: Constructing ArrayMapping('1x', 'b') or using a sharding-rule string where a factor token starts with a digit or '-' (e.g. '0 i -> i', or negative-sign tokens parsed as factors).

Common situations: Typos in Einsum-like sharding rules; using dimension indices as factor names; copy-pasting from GSPMD replication strings.

Related errors

• Unknown character '{char}'
• A compound factor should contain at least two factors
• 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/140c4a3cdecd6e9b. Report an issue: GitHub.