jax-ml/jax · error · ValueError

Unknown character '{char}'

Error message

Unknown character '{char}'

What it means

Factor names in sharding rules may contain only letters, digits, and underscores after the first character. Any other character (e.g. '-', '.', ',', space) raises ValueError naming the offending character.

Source

Thrown at jax/_src/custom_partitioning_sharding_rule.py:41

# 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"

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

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Replace invalid characters with underscores or letters
2. Validate factor strings against ^[A-Za-z][A-Za-z0-9_]*$ before building rules
3. Rename mesh axes used as factors to alphanumeric/underscore form

Example fix

# before
ArrayMapping('batch-1', 'i')

# after
ArrayMapping('batch_1', 'i')

import re
def check_factor(f): assert re.fullmatch(r'[A-Za-z][A-Za-z0-9_]*', f), f

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

When it happens

Trigger: A factor like 'my-factor', 'x.y', or 'b ' in an ArrayMapping or sharding-rule string; stray separators inside factor tokens.

Common situations: Using hyphenated mesh axis names or embedding punctuation in factor names when writing Einsum-like notation.

Related errors

• Factor names have to start with a letter, but got '{factor[0
• 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/40be7aff7856847b. Report an issue: GitHub.