deezer/spleeter · error · ValueError

Invalid mask_extension parameter {extension}

Error message

Invalid mask_extension parameter {extension}

What it means

_extend_mask pads frequency masks to the full frame length using either 'average' or 'zeros' extension; any other mask_extension value raises ValueError. The value comes from the model parameters, typically set in the separator configuration.

Source

Thrown at spleeter/model/__init__.py:420

            tf.Tensor:
                Extended mask

        Raises:
            ValueError:
                If invalid mask_extension parameter is set.
        """
        extension = self._params["mask_extension"]
        # Extend with average
        # (dispatch according to energy in the processed band)
        if extension == "average":
            extension_row = tf.reduce_mean(mask, axis=2, keepdims=True)
        # Extend with 0
        # (avoid extension artifacts but not conservative separation)
        elif extension == "zeros":
            mask_shape = tf.shape(mask)
            extension_row = tf.zeros((mask_shape[0], mask_shape[1], 1, mask_shape[-1]))
        else:
            raise ValueError(f"Invalid mask_extension parameter {extension}")
        n_extra_row = self._frame_length // 2 + 1 - self._F
        extension = tf.tile(extension_row, [1, 1, n_extra_row, 1])
        return tf.concat([mask, extension], axis=2)

    def _build_masks(self):
        """
        Compute masks from the output spectrograms of the model.
        """
        output_dict = self.model_outputs
        stft_feature = self.stft_feature
        separation_exponent = self._params["separation_exponent"]
        output_sum = (
            tf.reduce_sum(
                [e ** separation_exponent for e in output_dict.values()], axis=0
            )
            + self.EPSILON
        )
        out = {}

View on GitHub (pinned to c8854001ac)

Solutions

1. Set mask_extension to exactly 'average' or 'zeros' in the configuration
2. Fix case/typo issues (e.g. 'zeros' not 'zero' or 'Zeros')
3. Omit the key to use the default extension if one is defined
4. Check the _extend_mask source branch chain for the accepted literals

Example fix

// before (config)
{"params": {"mask_extension": "zero"}}
// after
{"params": {"mask_extension": "zeros"}}

VALID_EXTENSIONS = {'average', 'zeros'}
ext = params.get('mask_extension')
if ext is not None and ext not in VALID_EXTENSIONS:
    raise ValueError(f"mask_extension must be one of {VALID_EXTENSIONS}, got {ext!r}")

def has_valid_mask_extension(params: dict) -> bool:
    ext = params.get('mask_extension')
    return ext is None or ext in ('average', 'zeros')

try:
    separator.separate(...)  # builds model with configured mask_extension
except ValueError as e:
    if 'Invalid mask_extension' in str(e):
        raise ConfigError(f"mask_extension must be 'average' or 'zeros': {e}") from e
    raise

When it happens

Trigger: Configuring model.params.mask_extension (or passing it programmatically) with a value other than 'average' or 'zeros', e.g. 'zero', 'Zeros', 'mirror', or 'repeat'.

Common situations: Typos in config files; users guessing valid extension modes; configs ported from other separation tools with different mask-extension vocabularies.

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

• No model function {model_type} found
• Unkwnown loss type: {loss_type}
• n_chunks_per_song must be positif
• Unknown mode {mode}
• {adapter_class_name} is not a valid AudioAdapter class

AI-assisted analysis of deezer/spleeter@c8854001ac (2026-08-28). Data as JSON: /api/errors/b15deada34d0a6e4. Report an issue: GitHub.