Mask Failure Explainer — Diagnostics

Your mask has holes in the hair, eats into the background, or just looks off, and you don't know whether to blame the model, the image, or your prompt. Mask Failure Explainer (MEC) is the diagnostic that answers that. It analyzes your image + mask pair, scores five failure causes, and - the useful part - tells you which masking method to try next. Pure tensor analysis, no models, no VRAM, instant.

The README positions it exactly right: "a node that tells them why their mask failed." That's the pitch, and it delivers.

How it works

It runs a five-metric pipeline against your image and mask:

• Brightness - BT.709 mean luminance; a very dark scene (< 0.15) starves most segmenters.
• Blur - Laplacian variance; a blurry image (< 50) gives everyone soft, mushy edges.
• Boundary contrast - the std-dev of pixels in a ring around the mask edge; low contrast there (< 0.05) means the model had nothing to lock onto.
• Color confusion - mean color distance inside vs. outside the mask; low separation means foreground and background are the same color family, and no brightness-based method will separate them.
• Background complexity - Sobel edge density outside the mask; a busy background makes segmenters latch onto the wrong stuff.

Each metric contributes up to 20 points to a severity_score out of 100. Outputs: explanation (the human-readable verdict), problem_regions_mask (a heatmap of the pixels most likely to be wrong - very handy for spotting where), severity_score, and suggested_method (a string like "try ViTMatte for complex edges" or "use BiRefNet for busy backgrounds").

Three tunables: ring_width (boundary-ring size for the contrast analysis), blur_threshold, and brightness_threshold - you'll rarely touch any of them; the defaults are sane.

How to actually use it

The classic loop: generate a mask, look at it, suspect it's bad, and instead of re-rolling blindly, plug image + mask into this node and read the verdict. It converts a vague "bad mask" into a specific cause and a specific next step - which matches the pack's whole philosophy of telling you what to try rather than handing you a black box.

It's also a great teaching tool. Beginners blame themselves or the SAM model for failures that are really a dark frame or a low-contrast edge, and this node separates those cleanly. And it's embedded in the big MaskOpsMEC node (as enable_diagnose), so the flagstone pipeline can self-report its own failures.

Install

Standard pack install:

cd ComfyUI/custom_nodes
git clone https://github.com/Code2Collapse/ComfyUI-CustomNodePacks.git

or ComfyUI Manager → search "CustomNodePacks", restart, confirm the [MEC] Loaded ... console line. No dependencies beyond torch. One framing note: the explainer diagnoses the image conditions around a mask, not the mask itself - a severe score is a statement about why segmentation struggled, which is exactly the information you need when choosing the next tool.