microsoft/semantic-kernel · error · ArgumentOutOfRangeException

MaximumTokens

Error message

MaximumTokens

What it means

Thrown as an ArgumentOutOfRangeException during BertOnnxOptions initialization when the MaximumTokens property is set to a value less than 1. BERT models require at least one token to encode; zero or negative values are meaningless. The property uses an init-only setter that validates on construction.

Source

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

    private int _maximumTokens = 512;
    private string _clsToken = "[CLS]";
    private string _unknownToken = "[UNK]";
    private string _sepToken = "[SEP]";
    private string _padToken = "[PAD]";
    private EmbeddingPoolingMode _poolingMode = EmbeddingPoolingMode.Mean;

    /// <summary>Gets or sets whether the vocabulary employed by the model is case-sensitive.</summary>
    public bool CaseSensitive { get; init; } = false;

    /// <summary>Gets or sets the maximum number of tokens to encode. Defaults to 512.</summary>
    public int MaximumTokens
    {
        get => this._maximumTokens;
        init
        {
            if (value < 1)
            {
                throw new ArgumentOutOfRangeException(nameof(this.MaximumTokens));
            }

            this._maximumTokens = value;
        }
    }

    /// <summary>Gets or sets the cls token. Defaults to "[CLS]".</summary>
    public string ClsToken
    {
        get => this._clsToken;
        init
        {
            Verify.NotNullOrWhiteSpace(value);
            this._clsToken = value;
        }
    }

    /// <summary>Gets or sets the unknown token. Defaults to "[UNK]".</summary>

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set MaximumTokens to a positive integer (the default is 512).
2. Validate configuration values before assigning them to BertOnnxOptions.
3. If computing dynamically, clamp to a minimum of 1: Math.Max(1, computedValue).

Example fix

// before
var options = new BertOnnxOptions { MaximumTokens = 0 };

// after
var options = new BertOnnxOptions { MaximumTokens = 512 };

int maxTokens = config.GetValue<int>("Bert:MaximumTokens");
if (maxTokens < 1) maxTokens = 512; // safe default

static bool IsValidMaxTokens(int value) => value >= 1;

When it happens

Trigger: Setting BertOnnxOptions.MaximumTokens to 0 or a negative value, or loading a configuration that deserializes to 0 (e.g., a missing or empty config key that defaults to 0).

Common situations: Configuration file with a missing or blank MaximumTokens value that parses to 0; dynamically computing token limits from a ratio that rounds down to 0; copy-paste error from a template.

Related errors

• PoolingMode
• 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/daf90f608df1932b. Report an issue: GitHub.