microsoft/semantic-kernel · error · ArgumentOutOfRangeException

PoolingMode

Error message

PoolingMode

What it means

Thrown as an ArgumentOutOfRangeException during BertOnnxOptions initialization when PoolingMode is set to a value other than Max, Mean, or MeanSquareRootTokensLength. These are the only pooling strategies the BERT ONNX embedding service supports. Using an undefined enum value or an unsupported one triggers the error.

Source

Thrown at dotnet/src/Connectors/Connectors.Onnx/BertOnnxOptions.cs:91

        init
        {
            Verify.NotNullOrWhiteSpace(value);
            this._padToken = value;
        }
    }

    /// <summary>Gets or sets the type of Unicode normalization to perform on input text. Defaults to <see cref="NormalizationForm.FormD"/>.</summary>
    public NormalizationForm UnicodeNormalization { get; init; } = NormalizationForm.FormD;

    /// <summary>Gets or sets the pooling mode to use when generating the fixed-length embedding result. Defaults to "mean".</summary>
    public EmbeddingPoolingMode PoolingMode
    {
        get => this._poolingMode;
        init
        {
            if (value is not (EmbeddingPoolingMode.Max or EmbeddingPoolingMode.Mean or EmbeddingPoolingMode.MeanSquareRootTokensLength))
            {
                throw new ArgumentOutOfRangeException(nameof(this.PoolingMode));
            }

            this._poolingMode = value;
        }
    }

    /// <summary>Gets or sets whether the resulting embedding vectors should be explicitly normalized. Defaults to false.</summary>
    /// <remarks>Normalized embeddings may be compared more efficiently, such as by using a dot product rather than cosine similarity.</remarks>
    public bool NormalizeEmbeddings { get; set; } = false;
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Use EmbeddingPoolingMode.Mean (default), .Max, or .MeanSquareRootTokensLength.
2. Validate the pooling mode string against supported values before assignment.
3. If using 'cls' pooling, note it is not supported by this connector; consider a different ONNX embedding service.

Example fix

// before
var options = new BertOnnxOptions { PoolingMode = (EmbeddingPoolingMode)99 };

// after
var options = new BertOnnxOptions { PoolingMode = EmbeddingPoolingMode.Mean };

var supported = new[]
{
    EmbeddingPoolingMode.Max,
    EmbeddingPoolingMode.Mean,
    EmbeddingPoolingMode.MeanSquareRootTokensLength
};
if (!supported.Contains(configuredPooling))
    throw new InvalidOperationException("Unsupported pooling mode.");

static bool IsValidPoolingMode(EmbeddingPoolingMode mode) =>
    mode is EmbeddingPoolingMode.Max or
           EmbeddingPoolingMode.Mean or
           EmbeddingPoolingMode.MeanSquareRootTokensLength;

When it happens

Trigger: Setting PoolingMode to EmbeddingPoolingMode.None or any value outside the three supported modes; deserializing a config string that maps to an unsupported enum value.

Common situations: Configuration specifies a pooling mode string like 'none' or 'cls' that is not supported; enum cast from an integer that does not correspond to a valid supported mode; copy from a different model's config that uses a different pooling strategy.

Related errors

• MaximumTokens
• Expected output length {modelOutput.Length} to be a multiple
• Error creating OnnxGenAISettings: {e}
• AI model path is not provided. Please provide the 'ai_model_
• Invalid settings for OnnxGenAITextCompletion: {e}

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/01dac53c5400c824. Report an issue: GitHub.