microsoft/semantic-kernel · error · NotSupportedException

The provided response modalities JSON array may only contain

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.

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)

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.