microsoft/semantic-kernel · error · ArgumentException

MaxNewTokens {maxNewTokens} is not valid, the value must be

Error message

MaxNewTokens {maxNewTokens} is not valid, the value must be greater than or equal to zero

What it means

Thrown by HuggingFaceClient.ValidateMaxNewTokens when maxNewTokens is less than 0 (a negative value). maxNewTokens may be 0 (generate nothing new) but cannot be negative. Used by the chat/message request path.

Source

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

        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);

        var body = await response.Content.ReadAsStringWithExceptionMappingAsync(cancellationToken)
            .ConfigureAwait(false);

        return body;
    }

    internal async Task<HttpResponseMessage> SendRequestAndGetResponseImmediatelyAfterHeadersReadAsync(
        HttpRequestMessage httpRequestMessage,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set MaxNewTokens to 0 or a positive integer, or leave it null for the default.
2. Clamp user-supplied values to max(0, value) before assigning.
3. Check for arithmetic that can produce negatives (e.g. budget - used).

Example fix

// before
var settings = new HuggingFacePromptExecutionSettings { MaxNewTokens = -5 };  // throws

// after
var settings = new HuggingFacePromptExecutionSettings { MaxNewTokens = Math.Max(0, requested) };

static int? ClampMaxNewTokens(int? v) => v is < 0 ? throw new ArgumentException("MaxNewTokens must be >= 0") : v;

static bool IsValidMaxNewTokens(int? v) => v is null or >= 0;

When it happens

Trigger: Setting MaxNewTokens to a negative number on HuggingFacePromptExecutionSettings and invoking a chat or text-generation service that uses the new-tokens parameter.

Common situations: Passing an unvalidated negative value from config; subtracting budgets that underflow below zero; misreading the bound (it allows 0, not 1).

Related errors

• MaxTokens {maxTokens} is not valid, the value must be greate
• 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/d4f1bc572f21639a. Report an issue: GitHub.