{"record":{"id":"56f9910322d47a4f","repo":"microsoft/semantic-kernel","slug":"the-option-key-key-must-be-a-non-null-value","errorCode":null,"errorMessage":"The option key '{key}' must be a non null value.","messagePattern":"The option key '(.+?)' must be a non null value\\.","errorType":"validation","errorClass":"ArgumentNullException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/AzureAI/Extensions/AgentToolDefinitionExtensions.cs","lineNumber":244,"sourceCode":"    {\n        Verify.NotNull(agentToolDefinition.Options);\n\n        List<object> toolConnections = agentToolDefinition.GetRequiredOption<List<object>>(\"tool_connections\");\n\n        return [.. toolConnections.Select(connectionId => $\"{connectionId}\")];\n    }\n\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":226,"sourceCodeEnd":259,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/AzureAI/Extensions/AgentToolDefinitionExtensions.cs#L226-L259","documentation":"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).","triggerScenarios":"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.","commonSituations":"Agent definition sets an option to null/empty; deserialization produced a null entry; user cleared a value expecting it to be optional.","solutions":["Provide a non-null value for the option key.","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."],"exampleFix":"// before\noptions:\n  storage_queue: null\n// GetRequiredOption -> throws 167\n\n// after\noptions:\n  storage_queue:\n    storage_service_endpoint: https://...\n    queue_name: myqueue","handlingStrategy":"validation","validationCode":"if (tool.Options != null && tool.Options.TryGetValue(key, out var v) && v == null)\n    throw new InvalidOperationException($\"Option '{key}' is present but null; supply a value or remove the key.\");","typeGuard":"static bool OptionHasNonNullValue(AgentToolDefinition t, string key) =>\n    t.Options is not null && t.Options.TryGetValue(key, out var v) && v is not null;","tryCatchPattern":"try { var v = tool.GetRequiredOption<T>(key); }\ncatch (ArgumentNullException ex) when (ex.Message.Contains(key))\n{ /* provide a non-null value for the option */ }","preventionTips":["Never set a required option to null; omit it if optional.","Distinguish 'absent' (169) from 'present-but-null' (167) when debugging."],"tags":["validation","options","null-reference","agent-tool"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}