microsoft/semantic-kernel · error · NotSupportedException

The provided response modalities JSON array may only…

Error message

The provided response modalities JSON array may only contain strings.

What it means

Thrown inside GetResponseModalities when executionSettings.Modalities is a JsonElement of ValueKind Array but deserializing it to IEnumerable<string> throws a JsonException — i.e. the array contains non-string elements (numbers, objects, booleans, null). The JsonException is wrapped in a NotSupportedException.

Solutions

Ensure the JSON 'modalities' array contains only string elements.
Validate the array element kinds before binding to settings.
Use valid enum names as strings inside the array.

Example fix

// before (config)
{ "modalities": ["Text", 1] }
// throws: The provided response modalities JSON array may only contain strings.

// after
{ "modalities": ["Text", "Audio"] }

Defensive patterns

Strategy: validation

Validate before calling

static bool IsStringArray(JsonElement el)
{
    if (el.ValueKind != JsonValueKind.Array) return false;
    foreach (var item in el.EnumerateArray())
        if (item.ValueKind != JsonValueKind.String) return false;
    return true;
}

Type guard

bool IsModalityStringArray(JsonElement el)
    => el.ValueKind == JsonValueKind.Array && el.EnumerateArray().All(i => i.ValueKind == JsonValueKind.String);

Try / catch

try { /* kernel call */ }
catch (NotSupportedException ex) when (ex.Message.Contains("JSON array may only contain strings"))
{ throw new ConfigurationException("'modalities' array must contain only string modality names.", ex); }

Prevention

Ensure every element of a JSON modalities array is a string.
Validate array element kinds before binding settings.
Use valid enum names as the array entries.

When it happens

Trigger: JSON config with "modalities": ["Text", 1] or "modalities": ["Text", {"x":1}] or "modalities": ["Text", null]. JsonSerializer.Deserialize<IEnumerable<string>> throws on the non-string element.

Common situations: Hand-editing config and accidentally mixing types in the modalities array. Programmatic generation of the JSON array with numeric/boolean values. Schema drift between producer and consumer.

Related errors

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

Appendix: source

Thrown at dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.ChatCompletion.cs:210

                var modalityString = responseModalitiesElement.GetString();
                if (Enum.TryParse<ChatResponseModalities>(modalityString, true, out var parsedResponseModalities))
                {
                    return parsedResponseModalities;
                }

                throw new NotSupportedException($"The provided response modalities '{modalityString}' is not supported.");
            }

            if (responseModalitiesElement.ValueKind == JsonValueKind.Array)
            {
                try
                {
                    var modalitiesEnumeration = JsonSerializer.Deserialize<IEnumerable<string>>(responseModalitiesElement.GetRawText())!;
                    return ParseResponseModalitiesEnumerable(modalitiesEnumeration);
                }
                catch (JsonException ex)
                {
                    throw new NotSupportedException("The provided response modalities JSON array may only contain strings.", ex);
                }
            }

            throw new NotSupportedException($"The provided response modalities '{executionSettings.Modalities?.GetType()}' is not supported.");
        }

        return ChatResponseModalities.Default;
    }

    /// <summary>
    /// Gets the audio options from the execution settings.
    /// </summary>
    /// <param name="executionSettings">The execution settings.</param>
    /// <returns>The audio options as a <see cref="ChatAudioOptions"/> object.</returns>
    private static ChatAudioOptions GetAudioOptions(OpenAIPromptExecutionSettings executionSettings)
    {
        if (executionSettings.Audio is ChatAudioOptions audioOptions)
        {

View on GitHub (pinned to c028a0c7dc)