Comfy-Org/ComfyUI · error · ValueError

Either initial_mask or conditioning must be provided

Error message

Either initial_mask or conditioning must be provided

What it means

Raised by the SAM3 video tracking node when neither an initial_mask nor a usable conditioning is supplied. The node drives SAM3 either from an explicit first-frame mask or from text prompts extracted from conditioning; with both absent, forward_video has nothing to seed detection. Note the len(conditioning) > 0 guard: an empty conditioning list also counts as 'not provided'.

Source

Thrown at comfy_extras/nodes_sam3.py:305

        comfy.model_management.load_model_gpu(model)
        device = comfy.model_management.get_torch_device()
        dtype = model.model.get_dtype()
        sam3_model = model.model.diffusion_model

        frames_in = images[..., :3].movedim(-1, 1)

        init_masks = None
        if initial_mask is not None:
            init_masks = initial_mask.unsqueeze(1).to(device=device, dtype=dtype)

        pbar = comfy.utils.ProgressBar(N)

        text_prompts = None
        if conditioning is not None and len(conditioning) > 0:
            text_prompts = [(emb, mask) for emb, mask, _ in _extract_text_prompts(conditioning, device, dtype)]
        elif initial_mask is None:
            raise ValueError("Either initial_mask or conditioning must be provided")

        result = sam3_model.forward_video(
            images=frames_in, initial_masks=init_masks, pbar=pbar, text_prompts=text_prompts,
            new_det_thresh=detection_threshold, max_objects=max_objects,
            detect_interval=detect_interval, target_device=device, target_dtype=dtype)
        result["orig_size"] = (H, W)
        return io.NodeOutput(result)


class SAM3_TrackPreview(io.ComfyNode):
    """Visualize tracked objects with distinct colors as a video preview. No tensor output — saves to temp video."""

    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="SAM3_TrackPreview",
            display_name="SAM3 Track Preview",
            category="image/detection",

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Connect a text-prompt conditioning (e.g. SAM3 embedding/text encoder output) to the conditioning input.
2. Or connect a first-frame mask tensor to initial_mask.
3. If using conditioning, verify upstream that it is non-empty before this node.

Example fix

// before
SAM3Track(sam3_model, images, initial_mask=None, conditioning=[])
// after
SAM3Track(sam3_model, images, initial_mask=None, conditioning=text_conditioning)

if initial_mask is None and (conditioning is None or len(conditioning) == 0):
    raise ValueError("SAM3Track needs a non-empty conditioning or an initial_mask")

def has_sam3_seed(mask, conditioning) -> bool:
    return mask is not None or (conditioning is not None and len(conditioning) > 0)

When it happens

Trigger: Leaving both initial_mask and conditioning unconnected; or connecting a conditioning that is an empty list (len == 0), which falls into the elif initial_mask is None branch and raises.

Common situations: Wiring the wrong conditioning output (an empty list from a filtering node); forgetting to attach a SAM3Embedding/text-prompt upstream; batch setups where the conditioning path silently yields zero entries.

Related errors

• SAM3 (non-multiplex) requires initial_mask for video trackin
• Need at least {require_count} hooks to combine, but only had
• Input img and txt tensors must have 3 dimensions.
• Input txt tensors must have 3 dimensions.
• Scalar feature is not implemented yet.

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