Stability-AI/generative-models · error · ValueError

unknown merge strategy {self.merge_strategy}

Error message

unknown merge strategy {self.merge_strategy}

What it means

AlphaBlender.__init__ only accepts merge_strategy values 'learned', 'fixed', or 'learned_with_images' (class attribute AlphaBlender.strategies). Any other string raises ValueError('unknown merge strategy {merge_strategy}'). This guard exists because get_alpha cannot compute a blend factor for unknown strategies.

Source

Thrown at sgm/modules/diffusionmodules/util.py:369

        super().__init__()
        self.merge_strategy = merge_strategy
        self.rearrange_pattern = rearrange_pattern

        assert (
            merge_strategy in self.strategies
        ), f"merge_strategy needs to be in {self.strategies}"

        if self.merge_strategy == "fixed":
            self.register_buffer("mix_factor", torch.Tensor([alpha]))
        elif (
            self.merge_strategy == "learned"
            or self.merge_strategy == "learned_with_images"
        ):
            self.register_parameter(
                "mix_factor", torch.nn.Parameter(torch.Tensor([alpha]))
            )
        else:
            raise ValueError(f"unknown merge strategy {self.merge_strategy}")

    def get_alpha(self, image_only_indicator: torch.Tensor) -> torch.Tensor:
        if self.merge_strategy == "fixed":
            alpha = self.mix_factor
        elif self.merge_strategy == "learned":
            alpha = torch.sigmoid(self.mix_factor)
        elif self.merge_strategy == "learned_with_images":
            assert image_only_indicator is not None, "need image_only_indicator ..."
            alpha = torch.where(
                image_only_indicator.bool(),
                torch.ones(1, 1, device=image_only_indicator.device),
                rearrange(torch.sigmoid(self.mix_factor), "... -> ... 1"),
            )
            alpha = rearrange(alpha, self.rearrange_pattern)
        else:
            raise NotImplementedError
        return alpha

View on GitHub (pinned to e8cd657656)

Solutions

1. Use one of the supported strategies: 'fixed', 'learned', or 'learned_with_images'.
2. If you need 'fixed_with_images', use the video-model class that supports it (e.g. VideoResBlock in video_model.py), not AlphaBlender.
3. Validate against AlphaBlender.strategies before construction.

Example fix

// before
blend = AlphaBlender(alpha=0.5, merge_strategy="fixed_with_images")
// after
blend = AlphaBlender(alpha=0.5, merge_strategy="fixed")

SUPPORTED = {"fixed", "learned", "learned_with_images"}
if merge_strategy not in SUPPORTED:
    raise ValueError(f"merge_strategy must be one of {SUPPORTED}, got {merge_strategy!r}")

def is_valid_merge_strategy(s) -> bool:
    return isinstance(s, str) and s in {"fixed", "learned", "learned_with_images"}

try:
    blend = AlphaBlender(alpha=a, merge_strategy=strategy)
except ValueError as e:
    logger.warning("%s; falling back to 'fixed'", e)
    blend = AlphaBlender(alpha=a, merge_strategy="fixed")

When it happens

Trigger: Instantiating AlphaBlender(alpha=..., merge_strategy=...) with a misspelled or unsupported strategy, e.g. 'fixed_with_images' (which is only valid for the video_model variant, not AlphaBlender) or a typo like 'leanred'.

Common situations: Copying a merge_strategy value from the video-model config (which supports 'fixed_with_images') into an AlphaBlender config, or typos in YAML/CLI overrides.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unsupported dimensions: {dims}
• unknown merge strategy {merge_strategy}
• input has {x.ndim} dims but target_dims is {target_dims}, wh
• Model {model_id} not supported
• unknown discretization {params.discretization}

AI-assisted analysis of Stability-AI/generative-models@e8cd657656 (2026-08-29). Data as JSON: /api/errors/ae4699cdada8dbc2. Report an issue: GitHub.