microsoft/semantic-kernel · error · ArgumentException

The option key '{key}' was not found.

Error message

The option key '{key}' was not found.

What it means

Thrown by GetRequiredOption<T> when the option key is entirely absent from the options dictionary. Of the three GetRequiredOption failure modes, this is the 'key not present' case (contrast with null value 167 and wrong type 168). It throws ArgumentException.

Source

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

        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. Add the missing required option key with a value of the correct type.
2. Check the error message for the exact key name and the calling tool's documented required options.

Example fix

// before
options: {}
// GetRequiredOption('storage_queue') -> throws 169

// after
options:
  storage_queue:
    storage_service_endpoint: https://mystorage.queue.core.windows.net
    queue_name: myqueue

if (tool.Options is null || !tool.Options.ContainsKey(key))
    throw new InvalidOperationException($"Required option '{key}' is missing from the tool definition.");

static bool HasOption(AgentToolDefinition t, string key) =>
    t.Options is not null && t.Options.ContainsKey(key);

try { var v = tool.GetRequiredOption<T>(key); }
catch (ArgumentException ex) when (ex.Message.Contains("was not found"))
{ /* add the required option key with a proper value */ }

When it happens

Trigger: A required option key was never set on the AgentToolDefinition.Options dictionary, so TryGetValue returns false.

Common situations: Tool configuration omitted a mandatory key; typo in the key name; using a tool that requires options the developer didn't know about.

Related errors

• The option key '{key}' must be a non null value.
• The option key '{key}' value must be of type '{typeof(T)}' b
• 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/4c67d91e0b852886. Report an issue: GitHub.