What causes "Unknown DINOv2 backbone variant: {backbone_name!r}" in Comfy-Org/ComfyUI?

Print the table keys (sorted(_BACKBONE_PRESETS)) and use the exact preset key matching your checkpoint's backbone.

Comfy-Org/ComfyUI · error · ValueError

Unknown DINOv2 backbone variant: {backbone_name!r}

Error message

Unknown DINOv2 backbone variant: {backbone_name!r}

What it means

DepthAnything 3 selects a DINOv2 ViT backbone from a fixed preset table (_BACKBONE_PRESETS, e.g. ViT-S/B/L variants). _build_backbone_config() raises ValueError when backbone_name is not a key of that table. The backbone name is derived from the checkpoint config, so an unexpected name means the checkpoint is not a recognized DA3 model or the config parsing picked the wrong field.

Source

Thrown at comfy/ldm/depth_anything_3/model.py:40

# Backbone presets (mirror the upstream DINOv2 ViT variants).
_BACKBONE_PRESETS = {
    "vits": dict(hidden_size=384,  num_hidden_layers=12, num_attention_heads=6,  use_swiglu_ffn=False),
    "vitb": dict(hidden_size=768,  num_hidden_layers=12, num_attention_heads=12, use_swiglu_ffn=False),
    "vitl": dict(hidden_size=1024, num_hidden_layers=24, num_attention_heads=16, use_swiglu_ffn=False),
    "vitg": dict(hidden_size=1536, num_hidden_layers=40, num_attention_heads=24, use_swiglu_ffn=True),
}


def _build_backbone_config(
    backbone_name: str,
    *,
    alt_start: int,
    qknorm_start: int,
    rope_start: int,
    cat_token: bool,
) -> dict:
    if backbone_name not in _BACKBONE_PRESETS:
        raise ValueError(f"Unknown DINOv2 backbone variant: {backbone_name!r}")
    cfg = dict(_BACKBONE_PRESETS[backbone_name])
    cfg.update(dict(
        layer_norm_eps=1e-6,
        patch_size=14,
        image_size=518,
        # No mask_token in DA3 weights; omit param to avoid load warnings.
        use_mask_token=False,
        alt_start=alt_start,
        qknorm_start=qknorm_start,
        rope_start=rope_start,
        cat_token=cat_token,
        rope_freq=100.0,
    ))
    return cfg


class DepthAnything3Net(nn.Module):

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Print the table keys (sorted(_BACKBONE_PRESETS)) and use the exact preset key matching your checkpoint's backbone.
If your checkpoint is a legitimate new variant, add a preset entry derived from its config (embed dim, depth, num heads) rather than passing a free-form name.
If the name comes from config parsing, fix the extraction so it maps the checkpoint's backbone identifier to a preset key.

Example fix

# before
cfg = _build_backbone_config("ViT-B/14", ...)

# after
cfg = _build_backbone_config("vit_base_patch14_dinov2.lvd142m", ...)

Defensive patterns

Strategy: validation

Validate before calling

from comfy.ldm.depth_anything_3.model import _BACKBONE_PRESETS
assert backbone_name in _BACKBONE_PRESETS, f"backbone must be one of {sorted(_BACKBONE_PRESETS)}"

Type guard

def is_known_da3_backbone(name: str) -> bool:
    from comfy.ldm.depth_anything_3.model import _BACKBONE_PRESETS
    return name in _BACKBONE_PRESETS

Prevention

Derive the backbone name from the checkpoint config, never guess it.
When adding new DA3 checkpoints, verify their backbone name against the preset table first.

When it happens

Trigger: Loading a DepthAnything 3 checkpoint whose config yields a backbone name outside the presets (e.g. 'vitb14_pretrained' vs expected 'vit_base_patch14_dinov2.lvd142m'), or passing a manual backbone name with wrong casing/spacing.

Common situations: New DA3 releases with renamed backbones not yet in _BACKBONE_PRESETS; community-finetuned checkpoints with edited configs; custom nodes constructing the DA3 model directly with a guessed name.

Related errors

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