microsoft/semantic-kernel · error · InvalidOperationException

A valid model id or endpoint must be provided.

Error message

A valid model id or endpoint must be provided.

What it means

Thrown by the HuggingFaceClient constructor when both modelId is null/whitespace and no endpoint is available (the endpoint parameter is null and httpClient.BaseAddress is also null). The client needs at least one to know where to send requests.

Source

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

    internal string? ModelId { get; }
    internal string? ApiKey { get; }
    internal Uri Endpoint { get; }
    internal string Separator { get; }
    internal ILogger Logger { get; }

    internal HuggingFaceClient(
        HttpClient httpClient,
        string? modelId = null,
        Uri? endpoint = null,
        string? apiKey = null,
        ILogger? logger = null)
    {
        Verify.NotNull(httpClient);

        endpoint ??= httpClient.BaseAddress;
        if (string.IsNullOrWhiteSpace(modelId) && endpoint is null)
        {
            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");
        }

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Supply a non-empty modelId when constructing the HuggingFace service.
2. Or set HttpClient.BaseAddress to the HuggingFace inference endpoint.
3. Or pass an explicit endpoint Uri to the constructor.

Example fix

// before
var http = new HttpClient();  // no BaseAddress
var svc = new HuggingFaceTextGenerationService(modelId: null, httpClient: http);  // throws

// after
var svc = new HuggingFaceTextGenerationService(modelId: "gpt2", httpClient: http);

static void EnsureHfConfig(string? modelId, Uri? endpoint, HttpClient http)
{
    endpoint ??= http.BaseAddress;
    if (string.IsNullOrWhiteSpace(modelId) && endpoint is null)
        throw new InvalidOperationException("Provide a HuggingFace modelId or endpoint.");
}

static bool HasHfTarget(string? modelId, Uri? endpoint, HttpClient http)
    => !string.IsNullOrWhiteSpace(modelId) || endpoint is not null || http.BaseAddress is not null;

When it happens

Trigger: Constructing HuggingFaceTextGeneration / HuggingFaceChatCompletion / image services with a modelId of null AND an HttpClient that has no BaseAddress AND no explicit endpoint, then trying to build the client.

Common situations: Forgetting to pass a model id when using a bare HttpClient without a base address; misconfiguring DI registration where modelId is read from a null config key; using a custom HttpClient that was created without BaseAddress.

Related errors

• MaxTokens {maxTokens} is not valid, the value must be greate
• MaxNewTokens {maxNewTokens} is not valid, the value must be
• Invalid kernel selection. {selectedKernelName} is not a vali
• Azure AI Search tool definition must have both 'index_connec
• The option keys 'asset_identifiers' and 'asset_type' are req

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