Gemini API: candidateCount Parameter Returns Fewer Candidates Than Requested

[charlesf-blackore]

Thanks for stopping by to let us know something could be better!

PLEASE READ: If you have a support contract with Google, please create an issue in the support console instead of filing on GitHub. This will ensure a timely response.

Is this a client library issue or a product issue? We will only be able to assist with issues that pertain to the behaviors of this library. If the issue you're experiencing is due to the behavior of the product itself, please visit the Support page to reach the most relevant engineers.

If the support paths suggested above still do not result in a resolution, please provide the following details.

Environment details

• Programming language: Python
• OS: macOS
• Language runtime version: Python 3.11
• Package version: Version: 1.36.0

Steps to reproduce

Steps to reproduce

Set up a Vertex AI client using the google-genai SDK pointing to us-central1
Configure a GenerateContentConfig with candidate_count > 1:

from google import genai
from google.genai import types

generate_config = types.GenerateContentConfig(
       system_instruction=system_prompt,
       temperature=0.2,
       top_p=0.5,
       top_k=40,
       seed=42,
       candidate_count=5,  # Requesting 5 candidates
       max_output_tokens=12000,
       response_mime_type="text/plain",
       thinking_config=types.ThinkingConfig(thinkingBudget=-1),
   )

Call generate_content with an image input (PNG document):

response = await client.aio.models.generate_content(
       model="gemini-2.5-flash",
       contents=[image_part, prompt],
       config=generate_config,
   )

Check len(response.candidates) — intermittently returns fewer candidates than requested

The API returns fewer candidates than specified:

Prompt Type | Model | Requested | Returned
-- | -- | -- | --
one_prompt | gemini-2.5-flash | 5 | 3
twp_prompt | gemini-2.5-flash-lite | 3 | 1
three_prompt | gemini-2.5-flash | 5 | 5 ✓

Expected behavior
len(response.candidates) should equal the candidate_count value specified in the config (5 in this case).

Additional context

• All returned candidates have FinishReason.STOP, indicating successful completion

[janasangeetha]

They @charlesf-blackore
Thanks for reaching out!
I tried to reproduce the issue and observed len(response.candidates) is same as candidate_count. Please find the gist.
To assist us in effectively investigating and reproducing the issue, please provide a minimal, runnable code example with the image and prompt you have used.
Thank you!

[charlesf-blackore]

Hi @janasangeetha

Thanks for looking into this. I've done more investigation and can confirm the issue is intermittent, which may explain why you couldn't reproduce it.

Reproduction Details:

Here's a minimal reproduction script using the Vertex AI client:

  import asyncio
  from google import genai
  from google.genai import types

  async def test_candidate_count():
      client = genai.Client(
          vertexai=True,
          project="your-project",
          location="us-central1",
      )

      # Load your test image
      image_part = types.Part.from_bytes(
          data=open("test_image.png", "rb").read(),
          mime_type="image/png"
      )

      config = types.GenerateContentConfig(
          temperature=0.2,
          top_p=0.5,
          top_k=40,
          seed=42,
          candidate_count=5,
          max_output_tokens=12000,
          response_mime_type="text/plain",
      )

      response = await client.aio.models.generate_content(
          model="gemini-2.5-flash",
          contents=[image_part, "Extract data from this document as JSON"],
          config=config,
      )

      print(f"Requested: 5, Received: {len(response.candidates)}")
      for i, c in enumerate(response.candidates):
          has_content = bool(c.content and c.content.parts)
          print(f"  Candidate {i}: finish_reason={c.finish_reason}, has_content={has_content}")

  asyncio.run(test_candidate_count())

What I observed in production:

Prompt/Content Type	Model	Requested	Returned
Complex data extraction	gemini-2.5-flash	5	3
Writing detection	gemini-2.5-flash-lite	3	1
Info extraction	gemini-2.5-flash	5	5 ✓
Other extraction	gemini-2.5-flash-lite	5	5 ✓

The inconsistency across different prompt types with the same configuration suggests this may be related to:

• Prompt complexity or output length
• Server-side resource constraints
• Model-specific behavior that's non-deterministic
• Thinking - some use it and some dont'

Additional observation: In the Writing Detection case, the single returned candidate had no content/parts (candidate.content was empty), suggesting the API sometimes returns candidates without actual generated text.

Would it help if I provided a specific document image and prompt that triggers the reduced candidate count more reliably? I can also provide the full debug logs showing the API response structure.

[janasangeetha]

Hey @charlesf-blackore
Thanks for sharing reproducible code!
However, I'm still unable to reproduce the issue. Could you please share more details(image, prompt and the logs).