{"record":{"id":"2f4d291d42ecce38","repo":"microsoft/semantic-kernel","slug":"the-option-key-key-value-must-be-of-type-typ-2f4d29","errorCode":null,"errorMessage":"The option key '{key}' value must be of type '{typeof(T)}' but is '{value.GetType()}'.","messagePattern":"The option key '(.+?)' value must be of type '(.+?)' but is '(.+?)'\\.","errorType":"exception","errorClass":"InvalidCastException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/AzureAI/Extensions/AgentToolDefinitionExtensions.cs","lineNumber":251,"sourceCode":"\n    private static T GetRequiredOption<T>(this AgentToolDefinition agentToolDefinition, string key)\n    {\n        Verify.NotNull(agentToolDefinition);\n        Verify.NotNull(agentToolDefinition.Options);\n        Verify.NotNull(key);\n\n        if (agentToolDefinition.Options?.TryGetValue(key, out var value) ?? false)\n        {\n            if (value == null)\n            {\n                throw new ArgumentNullException($\"The option key '{key}' must be a non null value.\");\n            }\n\n            if (value is T expectedValue)\n            {\n                return expectedValue;\n            }\n            throw new InvalidCastException($\"The option key '{key}' value must be of type '{typeof(T)}' but is '{value.GetType()}'.\");\n        }\n\n        throw new ArgumentException($\"The option key '{key}' was not found.\");\n    }\n\n    private static readonly BinaryData s_noParams = BinaryData.FromObjectAsJson(new { type = \"object\", properties = new { } });\n}\n","sourceCodeStart":233,"sourceCodeEnd":259,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/AzureAI/Extensions/AgentToolDefinitionExtensions.cs#L233-L259","documentation":"Thrown by GetRequiredOption<T> when the option key exists and is non-null, but the value cannot be cast to the requested type T (the 'is T' pattern fails). It throws InvalidCastException, reporting both the expected and actual types. This usually means the agent definition supplied a scalar where a dictionary (or vice versa) was expected.","triggerScenarios":"GetRequiredOption<Dictionary<object,object>>(bindingType) is called but the option value is a string; or GetRequiredOption<int> is given a string. The runtime type does not match T.","commonSituations":"Indentation/scoping bug in YAML produced a scalar instead of a mapping; JSON value is a string where an object was expected; version mismatch where a new type constraint was added.","solutions":["Match the option value's shape to the expected type T (e.g., provide a nested mapping/object where a Dictionary<object,object> is required).","Check the agent definition file's indentation/structure.","Consult the tool's expected option schema for the exact type."],"exampleFix":"// before (scalar where dict expected)\nstorage_queue: 'https://mystorage...'\n// GetRequiredOption<Dictionary<object,object>> -> throws 168\n\n// after (object)\nstorage_queue:\n  storage_service_endpoint: https://mystorage.queue.core.windows.net\n  queue_name: myqueue","handlingStrategy":"type-guard","validationCode":"if (tool.Options != null && tool.Options.TryGetValue(key, out var v) && v is not null && v is not T)\n    throw new InvalidOperationException($\"Option '{key}' is {v.GetType()}, expected {typeof(T)}.\");","typeGuard":"static bool OptionHasType<T>(AgentToolDefinition t, string key) =>\n    t.Options is not null && t.Options.TryGetValue(key, out var v) && v is T;","tryCatchPattern":"try { var v = tool.GetRequiredOption<T>(key); }\ncatch (InvalidCastException ex) when (ex.Message.Contains(key))\n{ /* coerce/fix the option value type, then retry */ }","preventionTips":["Match the YAML/JSON value shape (scalar vs mapping) to the expected .NET type.","Watch YAML indentation - a misindented value becomes a scalar instead of a mapping."],"tags":["validation","type-mismatch","options","agent-tool"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}