What causes "The provided response format '{formatString}' is not supported." in microsoft/semantic-kernel?

Use 'url' (or 'uri') for URL responses, or 'b64_json' (or 'bytes') for base64 responses.

microsoft/semantic-kernel · error · NotSupportedException

The provided response format '{formatString}' is not support

Error message

The provided response format '{formatString}' is not supported.

What it means

When the response format is provided as a string, it is matched case-insensitively against URI/URL (for URL output) and BYTES/B64_JSON (for base64 output). Any other string value throws NotSupportedException. This check runs before the HTTP request is sent.

Source

Thrown at dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.TextToImage.cs:165

    private static GeneratedImageFormat? GetResponseFormat(object? responseFormat)
    {
        if (responseFormat is null)
        {
            return null;
        }

        if (responseFormat is GeneratedImageFormat format)
        {
            return format;
        }

        if (responseFormat is string formatString)
        {
            return formatString.ToUpperInvariant() switch
            {
                "URI" or "URL" => GeneratedImageFormat.Uri,
                "BYTES" or "B64_JSON" => GeneratedImageFormat.Bytes,
                _ => throw new NotSupportedException($"The provided response format '{formatString}' is not supported.")
            };
        }

        throw new NotSupportedException($"The provided response format type '{responseFormat.GetType()}' is not supported.");
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

Use 'url' (or 'uri') for URL responses, or 'b64_json' (or 'bytes') for base64 responses.
Pass a GeneratedImageFormat enum value directly to avoid string-matching errors.

Example fix

// before
var settings = new OpenAITextToImageExecutionSettings { ResponseFormat = "base64" };

// after
var settings = new OpenAITextToImageExecutionSettings { ResponseFormat = "b64_json" };

Defensive patterns

Strategy: validation

Validate before calling

static readonly HashSet<string> SupportedResponseFormats = new(StringComparer.OrdinalIgnoreCase)
{
    "uri", "url", "bytes", "b64_json"
};

void ValidateResponseFormat(string? format)
{
    if (format is not null && !SupportedResponseFormats.Contains(format.Trim()))
        throw new ArgumentOutOfRangeException(nameof(format),
            $"ResponseFormat string must be one of: {string.Join(", ", SupportedResponseFormats)}");
}

Try / catch

try { await imageService.GetTextToImageAsync(prompt, settings); }
catch (NotSupportedException ex) when (ex.Message.Contains("response format"))
{
    settings.ResponseFormat = null; // or GeneratedImageFormat.Url
    await imageService.GetTextToImageAsync(prompt, settings);
}

Prevention

Prefer passing GeneratedImageFormat enum values instead of strings to avoid typo errors.
Validate string settings loaded from configuration at startup.

When it happens

Trigger: Passing OpenAITextToImageExecutionSettings.ResponseFormat a string like 'json', 'base64', 'image', or a MIME type that does not match the four accepted tokens.

Common situations: Using OpenAI API docs shorthand ('b64' without '_json'). Passing a response-format string valid for a different endpoint (chat completions vs image generation). Confusing the format token with the output file format.

Related errors

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