{"record":{"id":"c885340da3e8e7bb","repo":"microsoft/autogen","slug":"the-response-should-contain-exactly-one-candidate","errorCode":null,"errorMessage":"The response should contain exactly one candidate.","messagePattern":"The response should contain exactly one candidate\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"dotnet/src/AutoGen.Gemini/Middleware/GeminiMessageConnector.cs","lineNumber":256,"sourceCode":"                return ProcessTextMessage(textMessage, agent);\n            }\n\n            return [];\n        }\n        else\n        {\n            var toolCallContents = ProcessToolCallMessage(toolCallAggregateMessage.Message1, agent);\n            var toolCallResultContents = ProcessToolCallResultMessage(toolCallAggregateMessage.Message2, agent);\n\n            return toolCallContents.Concat(toolCallResultContents);\n        }\n    }\n\n    private void ValidateGenerateContentResponse(GenerateContentResponse response)\n    {\n        if (response.Candidates.Count != 1)\n        {\n            throw new InvalidOperationException(\"The response should contain exactly one candidate.\");\n        }\n\n        var candidate = response.Candidates[0];\n        if (candidate.Content is null)\n        {\n            var finishReason = candidate.FinishReason;\n            var finishMessage = candidate.FinishMessage;\n\n            throw new InvalidOperationException($\"The response should contain content but the content is empty. FinishReason: {finishReason}, FinishMessage: {finishMessage}\");\n        }\n    }\n\n    private IEnumerable<IMessage> ProcessToolCallResultMessage(ToolCallResultMessage toolCallResultMessage, IAgent _)\n    {\n        var functionCallResultParts = new List<Part>();\n        foreach (var toolCallResult in toolCallResultMessage.ToolCalls)\n        {\n            if (toolCallResult.Result is null)","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/dotnet/src/AutoGen.Gemini/Middleware/GeminiMessageConnector.cs#L238-L274","documentation":"GeminiMessageConnector.ValidateGenerateContentResponse requires every GenerateContentResponse to carry exactly one candidate, because PostProcessMessage/PostProcessStreamingMessage index Candidates[0] unconditionally. If response.Candidates.Count is 0 (or >1) this InvalidOperationException is thrown before any part inspection.","triggerScenarios":"Any GeminiAgent reply where the API returns zero candidates — typically when the prompt/request is blocked (safety, prohibited content, recitation) or the response is an error-ish payload with an empty candidate list; or a candidateCount > 1 configuration.","commonSituations":"Safety settings block the prompt (promptFeedback.blockReason set, candidates empty); requesting candidateCount > 1 in GenerateContentConfig; API version drift where blocked responses no longer include a placeholder candidate.","solutions":["Inspect response.PromptFeedback.BlockReason for zero-candidate responses and adjust the prompt or SafetySettings.","Ensure candidateCount is left at 1 in GenerateContentConfig — the connector cannot merge multiple candidates.","Catch InvalidOperationException and treat it as a blocked/failed generation, falling back to a rephrased prompt.","Upgrade AutoGen.Gemini for improved handling of blocked responses."],"exampleFix":"// before\nvar config = new GenerateContentRequest { Config = new GenerateContentConfig { CandidateCount = 2 } };\n\n// after\nvar config = new GenerateContentRequest { Config = new GenerateContentConfig { CandidateCount = 1 } };","handlingStrategy":"validation","validationCode":"if (response.Candidates is null || response.Candidates.Count != 1)\n{\n    var block = response.PromptFeedback?.BlockReason;\n    // treat as blocked/failed generation, do not call the connector\n}","typeGuard":null,"tryCatchPattern":"try { var reply = await geminiAgent.SendAsync(msg); } catch (InvalidOperationException ex) when (ex.Message.Contains(\"exactly one candidate\")) { /* blocked prompt: rewrite and retry */ }","preventionTips":["Never set CandidateCount > 1 with this connector","Check PromptFeedback on suspicious prompts","Relax SafetySettings only as needed"],"tags":["gemini","candidates","safety-filter","invalid-operation"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}