microsoft/semantic-kernel · error · ArgumentException

MaxTokens {maxTokens} is not valid, the value must be greate

Error message

MaxTokens {maxTokens} is not valid, the value must be greater than zero

What it means

Thrown by HuggingFaceClient.ValidateMaxTokens when the maxTokens setting is less than 1 (a negative value or zero). Text-generation max token counts must be positive. Used by the older text-generation request path (MaxTokens).

Source

Thrown at dotnet/src/Connectors/Connectors.HuggingFace/Core/HuggingFaceClient.cs:61

        {
            throw new InvalidOperationException("A valid model id or endpoint must be provided.");
        }

        endpoint ??= new Uri("https://api-inference.huggingface.co");
        this.Separator = endpoint.AbsolutePath.EndsWith("/", StringComparison.InvariantCulture) ? string.Empty : "/";
        this.Endpoint = endpoint;
        this.ModelId = modelId;
        this.ApiKey = apiKey;
        this._httpClient = httpClient;
        this.Logger = logger ?? NullLogger.Instance;
    }

    #region ClientCore
    internal static void ValidateMaxTokens(int? maxTokens)
    {
        if (maxTokens is < 1)
        {
            throw new ArgumentException($"MaxTokens {maxTokens} is not valid, the value must be greater than zero");
        }
    }

    internal static void ValidateMaxNewTokens(int? maxNewTokens)
    {
        if (maxNewTokens is < 0)
        {
            throw new ArgumentException($"MaxNewTokens {maxNewTokens} is not valid, the value must be greater than or equal to zero");
        }
    }

    internal async Task<string> SendRequestAndGetStringBodyAsync(
        HttpRequestMessage httpRequestMessage,
        CancellationToken cancellationToken)
    {
        using var response = await this._httpClient.SendWithSuccessCheckAsync(httpRequestMessage, cancellationToken)
            .ConfigureAwait(false);

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set MaxTokens to a positive integer (>=1) or leave it null to use the model default.
2. Validate configuration before invoking: reject values < 1.
3. If you meant the chat-style setting, use MaxNewTokens instead (which allows 0).

Example fix

// before
var settings = new HuggingFacePromptExecutionSettings { MaxTokens = 0 };  // throws

// after
var settings = new HuggingFacePromptExecutionSettings { MaxTokens = 100 };
// or omit to use default
var settings = new HuggingFacePromptExecutionSettings();

static int? ClampMaxTokens(int? v) => v is < 1 ? throw new ArgumentException("MaxTokens must be >= 1") : v;

static bool IsValidMaxTokens(int? v) => v is null or >= 1;

When it happens

Trigger: Setting MaxTokens to 0 or a negative number on HuggingFacePromptExecutionSettings for a text-generation (non-chat) request and invoking the service.

Common situations: Passing MaxTokens from an unvalidated user/config value of 0; confusing MaxTokens (>=1) with MaxNewTokens (>=0); arithmetic that underflows to a negative.

Related errors

• MaxNewTokens {maxNewTokens} is not valid, the value must be
• MaxTokens {maxTokens} is not valid, the value must be greate
• A valid model id or endpoint must be provided.
• Invalid kernel selection. {selectedKernelName} is not a vali
• Azure AI Search tool definition must have both 'index_connec

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