{"record":{"id":"1d3ff74f134cff65","repo":"microsoft/semantic-kernel","slug":"gemini-api-doesn-t-support-author-role-value","errorCode":null,"errorMessage":"Gemini API doesn't support author role: {value}","messagePattern":"Gemini API doesn't support author role: (.+?)","errorType":"exception","errorClass":"JsonException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Connectors/Connectors.Google/Core/Gemini/AuthorRoleConverter.cs","lineNumber":60,"sourceCode":"            writer.WriteNullValue();\n            return;\n        }\n\n        if (value == AuthorRole.Tool)\n        {\n            writer.WriteStringValue(\"function\");\n        }\n        else if (value == AuthorRole.Assistant)\n        {\n            writer.WriteStringValue(\"model\");\n        }\n        else if (value == AuthorRole.User)\n        {\n            writer.WriteStringValue(\"user\");\n        }\n        else\n        {\n            throw new JsonException($\"Gemini API doesn't support author role: {value}\");\n        }\n    }\n}\n","sourceCodeStart":42,"sourceCodeEnd":64,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Connectors/Connectors.Google/Core/Gemini/AuthorRoleConverter.cs#L42-L64","documentation":"Thrown by AuthorRoleConverter.Write (the JSON serialization path) when attempting to serialize an AuthorRole that is not AuthorRole.Tool, AuthorRole.Assistant, or AuthorRole.User. Gemini's API only accepts 'function', 'model', and 'user' as role values, so any other AuthorRole cannot be written.","triggerScenarios":"Adding a chat history message with a role that is not User, Assistant, or Tool (e.g. AuthorRole.System or a custom role label) and sending it to the Gemini connector. The Write method is invoked when SK serializes the chat history into the Gemini request payload.","commonSituations":"Using AuthorRole.System in chat history sent to Gemini — Gemini handles system messages via a separate systemInstruction field, not as a role in the contents array. Creating a custom AuthorRole with a label like 'developer' or 'system'. Sharing chat history across multiple connectors where one supports a role Gemini does not.","solutions":["Remove System role messages from the chat history sent to Gemini, or use the Gemini-specific system instruction mechanism if available.","Ensure all messages use AuthorRole.User, AuthorRole.Assistant, or AuthorRole.Tool.","Filter or transform chat history before passing it to the Gemini connector: var filtered = history.Where(m => m.Role is null || m.Role == AuthorRole.User || m.Role == AuthorRole.Assistant || m.Role == AuthorRole.Tool).ToList();"],"exampleFix":"// before — System role causes serialization failure\nchatHistory.AddMessage(AuthorRole.System, \"You are a helpful assistant.\");\nawait geminiClient.GetChatMessageContentAsync(chatHistory);\n\n// after — move system message to GeminiPromptExecutionSettings or omit\nvar settings = new GeminiPromptExecutionSettings\n{\n    SystemInstruction = \"You are a helpful assistant.\"\n};\nawait geminiClient.GetChatMessageContentAsync(chatHistory, settings);","handlingStrategy":"validation","validationCode":"// Filter out unsupported roles before sending to Gemini\nvar supportedRoles = new[] { AuthorRole.User, AuthorRole.Assistant, AuthorRole.Tool };\nvar geminiHistory = new ChatHistory();\nforeach (var msg in history)\n{\n    if (msg.Role == AuthorRole.System)\n    {\n        // Move to system instruction\n        geminiSettings.SystemInstruction = msg.Content;\n    }\n    else if (msg.Role is null || supportedRoles.Contains(msg.Role))\n    {\n        geminiHistory.Add(msg);\n    }\n}","typeGuard":"static bool IsSupportedGeminiAuthorRole(AuthorRole? role) =>\n    role == AuthorRole.User ||\n    role == AuthorRole.Assistant ||\n    role == AuthorRole.Tool ||\n    role is null;","tryCatchPattern":"try { await client.GetChatMessageContentAsync(history, settings, ct); }\ncatch (JsonException ex) when (ex.Message.Contains(\"doesn't support author role\"))\n{\n    logger.LogError(\"Unsupported role in history. Supported: User, Assistant, Tool.\");\n    // Filter and retry\n}","preventionTips":["Do not use AuthorRole.System in chat history for Gemini — use GeminiPromptExecutionSettings.SystemInstruction instead.","Avoid creating custom AuthorRole labels when targeting Gemini.","Pre-filter chat history to only User, Assistant, and Tool roles before calling the Gemini connector."],"tags":["google","gemini","json","serialization","role","system-message"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}