diff --git a/docs/inference/use-google-gemini.mdx b/docs/inference/use-google-gemini.mdx
index 3f11f44c3d0..85171a77c9b 100644
--- a/docs/inference/use-google-gemini.mdx
+++ b/docs/inference/use-google-gemini.mdx
@@ -45,7 +45,11 @@ NemoClaw validates Gemini inference through its OpenAI-compatible Chat Completio
 When you enter a custom Gemini model ID, NemoClaw checks Google's native model catalog and accepts IDs with or without the `models/` prefix.
 It skips the Responses API probe because Gemini does not support `/v1/responses`.
 
+Google's native model catalog also lists embedding-only models, which do not support chat completions.
+NemoClaw filters these out of the catalog before matching your selection, so embedding-only models are never offered during onboarding and always fail validation if entered manually.
+
 ## Related Topics
 
 - [Choose a Model](../learn-and-choose/choose-model) compares the curated Gemini models by task fit.
 - [Understand Provider Validation](../validate-inference/understand-provider-validation) describes provider validation behavior.
+- [Troubleshooting](../../reference/troubleshooting#google-gemini-rejects-a-curated-or-custom-model) lists the error messages produced when a Gemini model fails validation.
diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx
index 0c53b560624..2750935b89e 100644
--- a/docs/reference/troubleshooting.mdx
+++ b/docs/reference/troubleshooting.mdx
@@ -1254,6 +1254,29 @@ bash uninstall.sh --yes
 curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
 ```
 
+### Google Gemini rejects a curated or custom model
+
+NemoClaw validates a selected Google Gemini model against Google's native model catalog (`https://generativelanguage.googleapis.com/v1beta/models`) before it creates the sandbox.
+That catalog includes embedding-only models, which do not support chat completions.
+NemoClaw filters out any model whose `supportedGenerationMethods` does not include `generateContent`, so embedding-only models never appear as selectable and always fail validation if entered manually.
+
+If the catalog request itself fails (invalid API key, network error, rate limit, or an outage), onboarding reports:
+
+```text
+Could not validate model against https://generativelanguage.googleapis.com/v1beta/models: {reason}
+```
+
+Check that `GEMINI_API_KEY` is set and valid, and that the host can reach `generativelanguage.googleapis.com`, then retry onboarding.
+
+If the catalog request succeeds but the selected model is not present in the filtered results, onboarding reports:
+
+```text
+Model '{model}' is not available from Google Gemini. Checked https://generativelanguage.googleapis.com/v1beta/models.
+```
+
+This means the model ID is either misspelled, not available to your API key or account tier, or is an embedding-only model (for example, an `embedding-*` or `text-embedding-*` model) that Google's catalog does not list under `generateContent`.
+NemoClaw accepts the model ID with or without the `models/` prefix. Verify the model name against the [curated Gemini models](../inference/hosted-inference/use-google-gemini#model-choices) or Google's published model list. Do not treat the optional prefix as a different model.
+
 ## Runtime
 
 <AgentOnly variant="openclaw">