microsoft/semantic-kernel · error · ArgumentNullException

The option key '{key}' must be a non null value.

Error message

The option key '{key}' must be a non null value.

What it means

Thrown by the generic GetRequiredOption<T> helper. The option key was found in the dictionary but its value is null. Because the contract requires a non-null value for required options, it throws ArgumentNullException. This is distinct from a missing key (169) and a wrong type (168).

Source

Thrown at dotnet/src/Agents/AzureAI/Extensions/AgentToolDefinitionExtensions.cs:244

    {
        Verify.NotNull(agentToolDefinition.Options);

        List<object> toolConnections = agentToolDefinition.GetRequiredOption<List<object>>("tool_connections");

        return [.. toolConnections.Select(connectionId => $"{connectionId}")];
    }

    private static T GetRequiredOption<T>(this AgentToolDefinition agentToolDefinition, string key)
    {
        Verify.NotNull(agentToolDefinition);
        Verify.NotNull(agentToolDefinition.Options);
        Verify.NotNull(key);

        if (agentToolDefinition.Options?.TryGetValue(key, out var value) ?? false)
        {
            if (value == null)
            {
                throw new ArgumentNullException($"The option key '{key}' must be a non null value.");
            }

            if (value is T expectedValue)
            {
                return expectedValue;
            }
            throw new InvalidCastException($"The option key '{key}' value must be of type '{typeof(T)}' but is '{value.GetType()}'.");
        }

        throw new ArgumentException($"The option key '{key}' was not found.");
    }

    private static readonly BinaryData s_noParams = BinaryData.FromObjectAsJson(new { type = "object", properties = new { } });
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Provide a non-null value for the option key.
2. If the option is genuinely optional, do not register the key at all (so the 'not found' path applies) or use a nullable accessor instead of GetRequiredOption.

Example fix

// before
options:
  storage_queue: null
// GetRequiredOption -> throws 167

// after
options:
  storage_queue:
    storage_service_endpoint: https://...
    queue_name: myqueue

if (tool.Options != null && tool.Options.TryGetValue(key, out var v) && v == null)
    throw new InvalidOperationException($"Option '{key}' is present but null; supply a value or remove the key.");

static bool OptionHasNonNullValue(AgentToolDefinition t, string key) =>
    t.Options is not null && t.Options.TryGetValue(key, out var v) && v is not null;

try { var v = tool.GetRequiredOption<T>(key); }
catch (ArgumentNullException ex) when (ex.Message.Contains(key))
{ /* provide a non-null value for the option */ }

When it happens

Trigger: Calling GetRequiredOption<T>(key) where the options dictionary contains key->null. Common when a YAML/JSON value is explicitly set to null or an empty mapping.

Common situations: Agent definition sets an option to null/empty; deserialization produced a null entry; user cleared a value expecting it to be optional.

Related errors

• The option key '{key}' value must be of type '{typeof(T)}' b
• The option key '{key}' was not found.
• Azure AI Search tool definition must have both 'index_connec
• The option keys 'name' and 'type' are required for a paramet
• The option keys 'asset_identifiers' and 'asset_type' are req

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