microsoft/semantic-kernel · error · KernelException

Unexpected response from model

Error message

Unexpected response from model

What it means

Thrown by HuggingFaceClient.DeserializeResponse<T> when JsonSerializer.Deserialize throws a JsonException (including a null-deserialization result wrapped as JsonException) while parsing the model response body. The original exception is passed as the inner exception and the raw body is stored in the KernelException.Data["ResponseData"] for diagnostics. This indicates the response did not match the expected DTO shape.

Source

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

    internal async Task<HttpResponseMessage> SendRequestAndGetResponseImmediatelyAfterHeadersReadAsync(
        HttpRequestMessage httpRequestMessage,
        CancellationToken cancellationToken)
    {
        var response = await this._httpClient.SendWithSuccessCheckAsync(httpRequestMessage, HttpCompletionOption.ResponseHeadersRead, cancellationToken)
            .ConfigureAwait(false);
        return response;
    }

    internal static T DeserializeResponse<T>(string body)
    {
        try
        {
            return JsonSerializer.Deserialize<T>(body) ??
                throw new JsonException("Response is null");
        }
        catch (JsonException exc)
        {
            throw new KernelException("Unexpected response from model", exc)
            {
                Data = { { "ResponseData", body } },
            };
        }
    }

    internal void SetRequestHeaders(HttpRequestMessage request)
    {
        request.Headers.Add("User-Agent", HttpHeaderConstant.Values.UserAgent);
        request.Headers.Add(HttpHeaderConstant.Names.SemanticKernelVersion, HttpHeaderConstant.Values.GetAssemblyVersion(this.GetType()));
        if (!string.IsNullOrEmpty(this.ApiKey))
        {
            request.Headers.Add("Authorization", $"Bearer {this.ApiKey}");
        }
    }

    internal HttpRequestMessage CreatePost(object requestData, Uri endpoint, string? apiKey)
    {

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect KernelException.Data["ResponseData"] to see the actual body and identify the schema mismatch or error.
2. Retry after the model finishes loading (HF returns estimated_time for cold models).
3. Verify the endpoint/model id and API key are correct and that the model supports the request type.
4. Upgrade the Semantic Kernel HuggingFace connector to a version matching the current HF Inference API schema.

Example fix

// before
var text = await svc.GetTextContentAsync(prompt, settings);  // throws Unexpected response

// after (capture raw body for diagnosis)
try { var text = await svc.GetTextContentAsync(prompt, settings); }
catch (KernelException ex)
{
    var raw = ex.Data.Contains("ResponseData") ? ex.Data["ResponseData"] : null;
    logger.LogError("HF returned unparseable body: {Body}", raw);
    throw;
}

try { var text = await svc.GetTextContentAsync(prompt, settings); }
catch (KernelException ex)
{
    var raw = ex.Data.Contains("ResponseData") ? ex.Data["ResponseData"]?.ToString() : "<none>";
    logger.LogError("HuggingFace unparseable response: {Body}", raw);
    // optionally retry once for cold-model loading
}

When it happens

Trigger: The HuggingFace Inference API returned a body that cannot be deserialized into the expected response type (e.g. an error JSON, HTML error page, a changed schema, truncated payload, or a model-load-in-progress message).

Common situations: Model still warming up (HF returns a transient estimate JSON); hitting a different inference endpoint revision with a different schema; API key/quota errors returning a non-payload JSON; network proxies injecting HTML; version mismatch between connector and HF API.

Related errors

• Unexpected response from model
• Response is not available.
• Failed to parse response: {responseText}
• Request failed: {nameof(GetUserProfileAsync)}
• Request failed: {nameof(GetRepositoryAsync)}

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