jax-ml/jax · error · ValueError

Unknown character '{BATCHING}'

Error message

Unknown character '{BATCHING}'

What it means

The parser internally represents ellipsis with a sentinel character (BATCHING). A literal occurrence of that sentinel character already in the rule string would be ambiguous and is rejected up front.

Source

Thrown at jax/_src/custom_partitioning_sharding_rule.py:343

  Args:
    rule: The Einsum notation like string for an operation.
    reduction_factors: A tuple of factors that are reduction factors.
    need_replication_factors: A tuple of factors that are need_replication factors.
    permutation_factors: A tuple of factors that are permutation factors.
    **factor_sizes: The optional factor sizes.

  Raises:
    ValueError: If there is any problem with the rule or factor_sizes.
  """
  if not isinstance(rule, str):
    raise TypeError(f"rule must be a str, but got {type(rule)}")
  if not all(isinstance(size, int) for size in factor_sizes.values()):
    raise TypeError(
        f"factor_sizes must be a dict of str to int, but got {factor_sizes}")

  # Replace ... with a single char to simplify parsing.
  if BATCHING in rule:
    raise ValueError(f"Unknown character '{BATCHING}'")
  if "." in rule:
    rule = rule.replace("...", BATCHING)
    if "." in rule:
      raise ValueError("Character '.' must be used inside ellipsis '...'")

  try:
    operands, results = rule.split("->")
  except ValueError as e:
    raise ValueError(f"There is no -> in rule: '{rule}'") from e

  operand_mappings = _parse_values(operands)
  result_mappings = _parse_values(results)
  return SdyShardingRule(operand_mappings, result_mappings,
                         reduction_factors=reduction_factors,
                         need_replication_factors=need_replication_factors,
                         permutation_factors=permutation_factors,
                         **factor_sizes)

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Remove the sentinel character from the rule; write ellipsis as '...'
2. If generating rules in code, restrict the alphabet to [A-Za-z0-9_(), ->.]

Example fix

# before
rule = 'i\x01,j->j'  # contains sentinel char
# after
rule = 'i,j->j'

import string
assert set(rule) <= set(string.ascii_letters + string.digits + '(), ._->')

def only_allowed_chars(rule: str) -> bool:
    import string
    return set(rule) <= set(string.ascii_letters + string.digits + '(), ._->')

When it happens

Trigger: Only triggered if the rule string contains the internal BATCHING sentinel char (a reserved non-printable/punctuation char); ordinary users essentially never hit this unless constructing rules programmatically with exotic characters.

Common situations: Programmatically building rule strings that embed unusual characters; copying rules from serialized dumps that contain the sentinel.

Related errors

• Compound factors should be one level, nested brackets are no
• Brackets are not balanced
• Brackets should contain at least two factors
• Factor names have to start with a letter, but got '{char}'
• Brackets are not balanced in rule: '{rule}'

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