BFS H3 Optional SAM 3.1 Model

A loader that checks nothing until you flip a switch

BFS H3 Optional SAM 3.1 Model has two fields and one output, and it exists entirely to make a graph with optional branches work without you rewiring it every time you change your mind.

The behaviour is the interesting part. enabled defaults to false. While it's off, the node returns nothing, doesn't touch the filesystem, and never complains that sam3.1_multiplex_fp16.safetensors isn't installed. Flip enabled on and it goes looking for that checkpoint in models/checkpoints and raises a specific, readable error if it isn't there. No auto-download, no silent substitution.

That's the whole design: the file-existence check is deferred to the moment you actually want SAM. Ten points to the author for this, honestly - the number of packs that crash on startup because an optional model is absent is embarrassing.

How it loads

It uses ComfyUI's own folder resolution and checkpoint guesser under the hood - folder_paths.get_full_path('checkpoints', checkpoint) then comfy.sd.load_checkpoint_guess_config - with output_vae=False and output_clip=False. Result: a single MODEL output that is the SAM 3.1 detector, not a diffusion model. There is deliberately no VAE or CLIP socket, because you don't need them and asking for them in a graph that also has an H3 video VAE loaded is asking for a confusing mix.

The MODEL output goes into BFS H3 SAM 3.1 Cast Tracking, which is the only consumer in this pack.

checkpoint is a plain string, not a combo list of the files you have. Typos are yours to find, and the error message does at least print the name it looked for.

Do you need this node at all?

No. Core CheckpointLoaderSimple will load the same file and give you the same MODEL. The pack's own docs say the workflow "includes the loader and model-download metadata," and the cast-tracking node's description points at CheckpointLoaderSimple directly.

So why use it? Because it's a switch. In the example h3_tara_optional_sam_loop.comfy.json there's a START HERE options node feeding use_sam31 into this loader's enabled. One workflow, two boolean toggles, and the SAM branch stays inert - no checkpoint required, no SAM inference, no wasted VRAM - until you tick the box. Wire the branch with a raw CheckpointLoaderSimple and that off-switch costs you a hard load every run.

If you always want SAM anyway, use the core loader and skip this node. If you're handing the workflow to someone else, this is the version that doesn't explode on their machine.

Install and the checkpoint

cd ComfyUI/custom_nodes
git clone https://github.com/alisson-anjos/ComfyUI-BFSNodes.git
cd ComfyUI-BFSNodes
pip install -r requirements.txt

Restart ComfyUI and hard-refresh the browser. Then put the weights where the node expects them:

ComfyUI/models/checkpoints/sam3.1_multiplex_fp16.safetensors

That's the Comfy-Org build published at huggingface.co/Comfy-Org/sam3.1. The README is explicit that nothing is fetched for you - which is the right call for a ~GB-scale checkpoint most users don't need. Note that the tracking node itself needs a ComfyUI with the native SAM 3 nodes in comfy_extras; a ComfyUI update, not a pip install.

The SAM 3 licence is Meta's custom SAM Licence rather than the Apache 2.0 that covered SAM and SAM 2. Worth a read if the output is going anywhere commercial.

Common issues

"SAM is enabled but its checkpoint is missing from models/checkpoints: …". The exact name has to match, including the _fp16 and the .safetensors extension. Subfolders work through ComfyUI's folder paths, so checkpoints/sam/sam3.1_multiplex_fp16.safetensors is fine - but then the field has to say sam/sam3.1_multiplex_fp16.safetensors.

The node "returns nothing" and the graph looks fine. That's enabled being false. It's not an error state; the downstream tracking node sees an empty bundle and no-ops.

You forgot you turned it on and it loads every run. The existence check is deferred, not the load. Once enabled, the model loads per execution like any other loader.

Wrong model in the field. It's the generic ComfyUI checkpoint guesser underneath, so it will try to interpret whatever file you name and hand back a MODEL. If the error arrives mid-tracking instead of at load time, check you pointed at the SAM file and not a diffusion checkpoint.