Comfy-Org/ComfyUI · error · ValueError

unsupported dimensions: {dims}

Error message

unsupported dimensions: {dims}

What it means

avg_pool_nd is a factory helper used by ComfyUI's diffusionmodules (Upsample/Downsample blocks) that maps an integer 'dims' to the matching torch AvgPool{1,2,3}d module. It raises ValueError when 'dims' is anything other than the literal integers 1, 2, or 3. In practice the value comes from model YAML/config (e.g. the 'dims' key of a UNet/VAE config), so this error almost always means a malformed or unsupported config rather than bad tensor data.

Source

Thrown at comfy/ldm/modules/diffusionmodules/util.py:287

def mean_flat(tensor):
    """
    Take the mean over all non-batch dimensions.
    """
    return tensor.mean(dim=list(range(1, len(tensor.shape))))


def avg_pool_nd(dims, *args, **kwargs):
    """
    Create a 1D, 2D, or 3D average pooling module.
    """
    if dims == 1:
        return nn.AvgPool1d(*args, **kwargs)
    elif dims == 2:
        return nn.AvgPool2d(*args, **kwargs)
    elif dims == 3:
        return nn.AvgPool3d(*args, **kwargs)
    raise ValueError(f"unsupported dimensions: {dims}")


class HybridConditioner(nn.Module):

    def __init__(self, c_concat_config, c_crossattn_config):
        super().__init__()
        self.concat_conditioner = instantiate_from_config(c_concat_config)
        self.crossattn_conditioner = instantiate_from_config(c_crossattn_config)

    def forward(self, c_concat, c_crossattn):
        c_concat = self.concat_conditioner(c_concat)
        c_crossattn = self.crossattn_conditioner(c_crossattn)
        return {'c_concat': [c_concat], 'c_crossattn': [c_crossattn]}


def noise_like(shape, device, repeat=False):
    repeat_noise = lambda: torch.randn((1, *shape[1:]), device=device).repeat(shape[0], *((1,) * (len(shape) - 1)))
    noise = lambda: torch.randn(shape, device=device)

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Inspect the model's embedded config (the YAML inside the diffusion checkpoint) and verify the dims key under the Upsample/Downsample block parameters is the integer 2 for image models (3 for video models).
2. If dims arrived as a string, change the config value to an unquoted integer, e.g. dims: 2 not dims: "2".
3. If the checkpoint really targets a non-standard architecture ComfyUI does not support, re-export or download the correct checkpoint variant instead of patching dims.
4. Only if you are writing custom model code, validate dims at config-parse time and fail with a clearer message before model construction.

Example fix

// before (config yaml)
params:
  dims: "2"
// after
params:
  dims: 2

def build_pool(dims, *args, **kwargs):
    if not isinstance(dims, int) or dims not in (1, 2, 3):
        raise ValueError(f"dims must be int 1, 2, or 3, got {dims!r} — check model config")
    return avg_pool_nd(dims, *args, **kwargs)

def is_valid_pool_dims(dims) -> bool:
    return isinstance(dims, int) and not isinstance(dims, bool) and dims in (1, 2, 3)

When it happens

Trigger: Calling comfy.ldm.modules.diffusionmodules.util.avg_pool_nd(dims, ...) with dims == 0, dims >= 4, a string like "2", or None. Happens transitively when instantiate_from_config builds an Upsample/Downsample whose parameters.dims is missing or mistyped, e.g. params: {dims: "2"} in the checkpoint's YAML config.

Common situations: Hand-edited or community-shared SD1.x/SD2.x UNet config YAML with a typo in the dims field; a config generated for a different codebase that uses "dimensions" or "dim" instead of "dims"; JSON configs that store dims as a string.

Related errors

• provide num_res_blocks either as an int (globally constant)
• INVALID_TAG_FILTER
• Control type {max_type_name}({max_type}) is out of range for
• Unknown pos_emb_cls {self.pos_emb_cls}
• Unknown pos_emb_cls {self.pos_emb_cls}

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/4ce354fa36a4847b. Report an issue: GitHub.