{"record":{"id":"42923ab566f4f290","repo":"Comfy-Org/ComfyUI","slug":"either-initial-mask-or-conditioning-must-be-provid","errorCode":null,"errorMessage":"Either initial_mask or conditioning must be provided","messagePattern":"Either initial_mask or conditioning must be provided","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_sam3.py","lineNumber":305,"sourceCode":"\n        comfy.model_management.load_model_gpu(model)\n        device = comfy.model_management.get_torch_device()\n        dtype = model.model.get_dtype()\n        sam3_model = model.model.diffusion_model\n\n        frames_in = images[..., :3].movedim(-1, 1)\n\n        init_masks = None\n        if initial_mask is not None:\n            init_masks = initial_mask.unsqueeze(1).to(device=device, dtype=dtype)\n\n        pbar = comfy.utils.ProgressBar(N)\n\n        text_prompts = None\n        if conditioning is not None and len(conditioning) > 0:\n            text_prompts = [(emb, mask) for emb, mask, _ in _extract_text_prompts(conditioning, device, dtype)]\n        elif initial_mask is None:\n            raise ValueError(\"Either initial_mask or conditioning must be provided\")\n\n        result = sam3_model.forward_video(\n            images=frames_in, initial_masks=init_masks, pbar=pbar, text_prompts=text_prompts,\n            new_det_thresh=detection_threshold, max_objects=max_objects,\n            detect_interval=detect_interval, target_device=device, target_dtype=dtype)\n        result[\"orig_size\"] = (H, W)\n        return io.NodeOutput(result)\n\n\nclass SAM3_TrackPreview(io.ComfyNode):\n    \"\"\"Visualize tracked objects with distinct colors as a video preview. No tensor output — saves to temp video.\"\"\"\n\n    @classmethod\n    def define_schema(cls):\n        return io.Schema(\n            node_id=\"SAM3_TrackPreview\",\n            display_name=\"SAM3 Track Preview\",\n            category=\"image/detection\",","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_sam3.py#L287-L323","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Connect a text-prompt conditioning (e.g. SAM3 embedding/text encoder output) to the conditioning input.","Or connect a first-frame mask tensor to initial_mask.","If using conditioning, verify upstream that it is non-empty before this node."],"exampleFix":"// before\nSAM3Track(sam3_model, images, initial_mask=None, conditioning=[])\n// after\nSAM3Track(sam3_model, images, initial_mask=None, conditioning=text_conditioning)","handlingStrategy":"validation","validationCode":"if initial_mask is None and (conditioning is None or len(conditioning) == 0):\n    raise ValueError(\"SAM3Track needs a non-empty conditioning or an initial_mask\")","typeGuard":"def has_sam3_seed(mask, conditioning) -> bool:\n    return mask is not None or (conditioning is not None and len(conditioning) > 0)","tryCatchPattern":null,"preventionTips":["Always wire at least one of initial_mask or a text-prompt conditioning before running.","Log len(conditioning) in upstream nodes to catch empty conditioning lists early."],"tags":["sam3","segmentation","tracking","conditioning","missing-input"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}