pytorch/pytorch · error · DimensionBindError

Dim '{repr(self)}' previously bound to a dimension of size {

Error message

Dim '{repr(self)}' previously bound to a dimension of size {self._size} cannot bind to a dimension of size {v}

What it means

A Dim is a persistent name that remembers the extent it was first bound to. The size setter allows exactly one binding; a second assignment with a different value raises DimensionBindError. This is by design: reusing the same Dim for two differently-sized dimensions would make named-indexing ambiguous, so the library enforces size consistency across the whole program.

Source

Thrown at functorch/dim/__init__.py:920

    def ndim(self) -> int:
        return 1

    @classmethod
    def check_exact(cls, obj: Any) -> bool:
        return type(obj) is cls

    @property
    def size(self) -> int:
        if self._size == -1:
            raise ValueError(f"dimension {self._name} is unbound")
        return self._size

    @size.setter
    def size(self, v: int) -> None:
        if self._size == -1:
            self._size = v
        elif self._size != v:
            raise DimensionBindError(
                f"Dim '{repr(self)}' previously bound to a dimension of size {self._size} "
                f"cannot bind to a dimension of size {v}"
            )

    @property
    def is_bound(self) -> bool:
        """Return True if this dimension is bound to a size."""
        return self._size != -1

    def _get_range(self) -> torch.Tensor:
        """
        Get a tensor representing the range [0, size) for this dimension.

        Returns:
            A 1D tensor with values [0, 1, 2, ..., size-1]
        """
        if self._range is None:
            self._range = torch.arange(self.size)

View on GitHub (pinned to dcd2ecae77)

Solutions

Create fresh Dim objects per shape: call dims(n) or construct new Dims inside the loop/function instead of reusing module-level ones.
If the shape is genuinely fixed, fix the data: make the incoming tensors agree with the already-bound size (e.g. pad/truncate or set a consistent batch size).
Catch DimensionBindError where variable-size inputs are legitimate, and rebuild the dims for that batch (see tryCatchPattern).

Example fix

d = dims(1)
_ = torch.zeros(4)[d]
_ = torch.zeros(8)[d]  # DimensionBindError

# after (fresh dim per shape)
for batch in batches:
    d = dims(1)
    _ = batch[d]

Defensive patterns

Strategy: try-catch

Validate before calling

if d.is_bound and d.size != expected:
    raise ValueError(f'{d!r} bound to {d.size}, data has {expected}')

Try / catch

from functorch.dim import DimensionBindError
try:
    _ = batch[d]
except DimensionBindError:
    d = dims(1)  # fresh dim for this batch's size
    _ = batch[d]

Prevention

Never share module-level Dim objects across differently-sized batches.
Create dims inside the training step, not once at import time.
Add a shape assert at the data boundary so mismatches surface as data errors, not bind errors.

When it happens

Trigger: Reusing one Dim object for tensor dimensions of different lengths: t1 = torch.zeros(4)[d]; t2 = torch.zeros(8)[d]. Also triggered inside split when unbound target dims get assigned sizes that conflict with an earlier binding, or in setitem/getitem dim packs where an inferred size disagrees with a prior bind.

Common situations: Copy-pasting a pipeline block that uses the same dims() objects on batches with a different sequence length; loop iterations where the first batch had seq_len=32 and the next has 64; mixing a global 'batch' Dim across models whose batch sizes differ.

Related errors

AI-assisted analysis of pytorch/pytorch@dcd2ecae77 (2026-08-14). Data as JSON: /api/errors/96f912523c818290. Report an issue: GitHub.