{"record":{"id":"390558a30905a18a","repo":"jax-ml/jax","slug":"convolution-dimension-numbers-must-contain-the","errorCode":null,"errorMessage":"convolution dimension_numbers[{}] must contain the characters '{}' and '{}' exactly once, got {}.","messagePattern":"convolution dimension_numbers\\[(.+?)\\] must contain the characters '(.+?)' and '(.+?)' exactly once, got (.+?)\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"jax/_src/lax/convolution.py","lineNumber":999,"sourceCode":"      if len(elt) != len(lhs_shape):\n        raise TypeError(msg.format(i, len(elt), lhs_shape, rhs_shape))\n\n    lhs_spec, rhs_spec, out_spec = conv_general_permutations(dimension_numbers)\n    return ConvDimensionNumbers(lhs_spec, rhs_spec, out_spec)\n  else:\n    msg = \"convolution dimension_numbers must be tuple/list or None, got {}.\"\n    raise TypeError(msg.format(type(dimension_numbers)))\n\n\ndef conv_general_permutations(dimension_numbers):\n  \"\"\"Utility for convolution dimension permutations relative to Conv HLO.\"\"\"\n  lhs_spec, rhs_spec, out_spec = dimension_numbers\n  lhs_char, rhs_char, out_char = charpairs = (\"N\", \"C\"), (\"O\", \"I\"), (\"N\", \"C\")\n  for i, (a, b) in enumerate(charpairs):\n    if not dimension_numbers[i].count(a) == dimension_numbers[i].count(b) == 1:\n      msg = (\"convolution dimension_numbers[{}] must contain the characters \"\n             \"'{}' and '{}' exactly once, got {}.\")\n      raise TypeError(msg.format(i, a, b, dimension_numbers[i]))\n    if len(dimension_numbers[i]) != len(set(dimension_numbers[i])):\n      msg = (\"convolution dimension_numbers[{}] cannot have duplicate \"\n             \"characters, got {}.\")\n      raise TypeError(msg.format(i, dimension_numbers[i]))\n  if not (set(lhs_spec) - set(lhs_char) == set(rhs_spec) - set(rhs_char) ==\n          set(out_spec) - set(out_char)):\n    msg = (\"convolution dimension_numbers elements must each have the same \"\n           \"set of spatial characters, got {}.\")\n    raise TypeError(msg.format(dimension_numbers))\n\n  def getperm(spec, charpair):\n    spatial = (i for i, c in enumerate(spec) if c not in charpair)\n    if spec is not rhs_spec:\n      spatial = sorted(spatial, key=lambda i: rhs_spec.index(spec[i]))\n    return (spec.index(charpair[0]), spec.index(charpair[1])) + tuple(spatial)\n\n  lhs_perm, rhs_perm, out_perm = map(getperm, dimension_numbers, charpairs)\n  return lhs_perm, rhs_perm, out_perm","sourceCodeStart":981,"sourceCodeEnd":1017,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/lax/convolution.py#L981-L1017","documentation":"In conv_general_permutations, each layout string must contain its two designated non-spatial characters exactly once: lhs and out must each contain 'N' and 'C' once, rhs must contain 'O' and 'I' once. Violations (missing, duplicated, or swapped) raise this TypeError naming the element index and required characters.","triggerScenarios":"Passing rhs layout 'OOHW' (two O's, no I) or lhs layout 'NHHW' (no C); using 'NCHW' for the kernel instead of 'OIHW'.","commonSituations":"Copy-pasting the input layout into the kernel position; typos in layout strings; misunderstanding that kernel layouts use O (out channels) and I (in channels).","solutions":["Use 'OIHW'/'HWIO' style layouts for the kernel: O and I exactly once","Ensure lhs/out layouts contain N and C exactly once","Prefer lax.conv_dimension_numbers and validated constants over hand-typed strings"],"exampleFix":"# before\ndn = lax.conv_dimension_numbers(x.shape, w.shape, ('NCHW', 'IIHW', 'NCHW'))\n# after\ndn = lax.conv_dimension_numbers(x.shape, w.shape, ('NCHW', 'OIHW', 'NCHW'))","handlingStrategy":"validation","validationCode":"required = [('N','C'), ('O','I'), ('N','C')]\nassert all(s.count(a) == s.count(b) == 1 for s, (a, b) in zip(dimension_numbers, required))","typeGuard":"def valid_layout_chars(dn) -> bool:\n    req = [('N','C'), ('O','I'), ('N','C')]\n    return all(s.count(a) == 1 and s.count(b) == 1 for s, (a, b) in zip(dn, req))","tryCatchPattern":null,"preventionTips":["Memorize kernel layouts use O/I (e.g. 'OIHW' or 'HWIO')","Never reuse the input layout string for the kernel"],"tags":["jax","convolution","dimension-numbers","validation"],"backgroundTag":"invalid-argument-format","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}