What causes "A valid model id or endpoint must be provided." in microsoft/semantic-kernel?

Supply a non-empty modelId when constructing the HuggingFace service.

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.

Solutions

Supply a non-empty modelId when constructing the HuggingFace service.
Or set HttpClient.BaseAddress to the HuggingFace inference endpoint.
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);

Defensive patterns

Strategy: validation

Validate before calling

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.");
}

Type guard

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

Prevention

Always pass a modelId when constructing HuggingFace services.
Or set HttpClient.BaseAddress / pass an endpoint.
Validate DI configuration keys are non-null at startup.

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

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

Appendix: 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)