From 9e69472526b915aa1776547eeec7a16f65be08ce Mon Sep 17 00:00:00 2001 From: Ashish Shrees <47479956+ashrees@users.noreply.github.com> Date: Fri, 14 Aug 2026 18:28:09 -0400 Subject: [PATCH 1/5] docs(gemini): document embedding-model filtering and validation errors The Gemini provider page did not mention that embedding-only models (those without generateContent support) are filtered out of the model catalog, and had no troubleshooting section for validation errors. Documents all validation messages emitted by src/lib/inference/provider-models.ts, including the model-availability and catalog-validation failures called out in the issue. Fixes #8971 Signed-off-by: ashrees --- docs/inference/use-google-gemini.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/inference/use-google-gemini.mdx b/docs/inference/use-google-gemini.mdx index 3f11f44c3d0..5c4f776b1d5 100644 --- a/docs/inference/use-google-gemini.mdx +++ b/docs/inference/use-google-gemini.mdx @@ -44,6 +44,20 @@ NemoClaw validates the selected provider and model before creating the sandbox. NemoClaw validates Gemini inference through its OpenAI-compatible Chat Completions path. 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`. +When NemoClaw reads the native Google model catalog, it keeps only models that support `generateContent`. +Embedding-only models are filtered out of the catalog, so they do not appear as onboarding choices. + +## Troubleshooting + +Model validation can fail with these messages: + +- `Could not validate model against https://generativelanguage.googleapis.com/v1beta/models: `: NemoClaw could not read the Google model catalog. The `` value shows the cause, such as an authentication or network failure. Make sure that `GEMINI_API_KEY` is valid and that the host can reach `generativelanguage.googleapis.com`. +- `Model '' is not available from Google Gemini. Checked https://generativelanguage.googleapis.com/v1beta/models.`: The catalog did not contain the model ID. Check the ID for typing errors. Custom IDs are accepted with or without the `models/` prefix. Embedding-only models do not appear in the catalog because they are filtered out. +- `Unexpected Gemini model catalog response: expected a top-level models array`: The Google model catalog did not return the expected data. Make sure that `GEMINI_API_KEY` is set and that the host can reach `generativelanguage.googleapis.com`. +- `Gemini model catalog pagination repeated page token ''`: The catalog returned the same page token twice, so NemoClaw stopped reading the catalog. Run the onboarding wizard again. +- `Gemini model catalog pagination exceeded pages`: The catalog search reached its page limit (`GEMINI_MODEL_CATALOG_MAX_PAGES`) before it found the model. Run the wizard again, or select one of the curated models. +- `Unexpected model catalog response: expected a top-level data array`: The OpenAI-compatible endpoint did not return the expected data. Check the provider configuration. +- `Onboard inference smoke check failed.`: The post-selection probe failed. The output shows the provider, model, and API base URL. Compare these values with your configuration. ## Related Topics From 6244c1a4c5022c02f494601dfd97181e6009644b Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 14 Aug 2026 16:06:19 -0700 Subject: [PATCH 2/5] docs(gemini): correct validation recovery guidance Signed-off-by: Carlos Villela --- docs/inference/use-google-gemini.mdx | 32 ++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/inference/use-google-gemini.mdx b/docs/inference/use-google-gemini.mdx index 5c4f776b1d5..3dcd6e07e55 100644 --- a/docs/inference/use-google-gemini.mdx +++ b/docs/inference/use-google-gemini.mdx @@ -51,13 +51,31 @@ Embedding-only models are filtered out of the catalog, so they do not appear as Model validation can fail with these messages: -- `Could not validate model against https://generativelanguage.googleapis.com/v1beta/models: `: NemoClaw could not read the Google model catalog. The `` value shows the cause, such as an authentication or network failure. Make sure that `GEMINI_API_KEY` is valid and that the host can reach `generativelanguage.googleapis.com`. -- `Model '' is not available from Google Gemini. Checked https://generativelanguage.googleapis.com/v1beta/models.`: The catalog did not contain the model ID. Check the ID for typing errors. Custom IDs are accepted with or without the `models/` prefix. Embedding-only models do not appear in the catalog because they are filtered out. -- `Unexpected Gemini model catalog response: expected a top-level models array`: The Google model catalog did not return the expected data. Make sure that `GEMINI_API_KEY` is set and that the host can reach `generativelanguage.googleapis.com`. -- `Gemini model catalog pagination repeated page token ''`: The catalog returned the same page token twice, so NemoClaw stopped reading the catalog. Run the onboarding wizard again. -- `Gemini model catalog pagination exceeded pages`: The catalog search reached its page limit (`GEMINI_MODEL_CATALOG_MAX_PAGES`) before it found the model. Run the wizard again, or select one of the curated models. -- `Unexpected model catalog response: expected a top-level data array`: The OpenAI-compatible endpoint did not return the expected data. Check the provider configuration. -- `Onboard inference smoke check failed.`: The post-selection probe failed. The output shows the provider, model, and API base URL. Compare these values with your configuration. +- `Could not validate model against https://generativelanguage.googleapis.com/v1beta/models: ` + NemoClaw could not read the Google model catalog. + The `` value identifies an authentication, network, response, or pagination failure. + Verify `GEMINI_API_KEY`, host access to `generativelanguage.googleapis.com`, and the reported response. +- `Model '' is not available from Google Gemini. Checked https://generativelanguage.googleapis.com/v1beta/models.` + The catalog did not contain the model ID. + Check the ID for typing errors. + Custom IDs can include or omit the `models/` prefix. + Embedding-only models do not appear because they do not support `generateContent`. +- `Unexpected Gemini model catalog response: expected a top-level models array` + The Google model catalog returned JSON with the wrong shape. + Retry the request, then inspect the Google service or proxy response if the error continues. +- `Gemini model catalog pagination repeated page token ''` + The catalog repeated a `nextPageToken`, so NemoClaw stopped reading pages. + Retry the request, then inspect the Google service or proxy response if the error continues. +- `Gemini model catalog pagination exceeded pages` + The catalog exhausted the 25-page `GEMINI_MODEL_CATALOG_MAX_PAGES` limit. + Retry the request, then inspect the Google service or proxy response if the error continues. +- `Unexpected model catalog response: expected a top-level data array` + The OpenAI-compatible endpoint returned JSON with the wrong shape. + Retry the request, then inspect the endpoint or proxy response if the error continues. +- `Onboard inference smoke check failed.` + The validation request failed. + The output shows the provider, model, and API base URL. + Compare these values with your configuration. ## Related Topics From 975460b35e7abc55b13818f2e0606b61b5c070db Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 14 Aug 2026 16:23:25 -0700 Subject: [PATCH 3/5] docs(gemini): remove unreachable catalog diagnostic Signed-off-by: Carlos Villela --- docs/inference/use-google-gemini.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/inference/use-google-gemini.mdx b/docs/inference/use-google-gemini.mdx index 3dcd6e07e55..7b9eca00462 100644 --- a/docs/inference/use-google-gemini.mdx +++ b/docs/inference/use-google-gemini.mdx @@ -69,9 +69,6 @@ Model validation can fail with these messages: - `Gemini model catalog pagination exceeded pages` The catalog exhausted the 25-page `GEMINI_MODEL_CATALOG_MAX_PAGES` limit. Retry the request, then inspect the Google service or proxy response if the error continues. -- `Unexpected model catalog response: expected a top-level data array` - The OpenAI-compatible endpoint returned JSON with the wrong shape. - Retry the request, then inspect the endpoint or proxy response if the error continues. - `Onboard inference smoke check failed.` The validation request failed. The output shows the provider, model, and API base URL. From 4fb7da68f4c956d6c6c1cc93bc45ae4de29a8831 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 14 Aug 2026 20:48:25 -0700 Subject: [PATCH 4/5] docs(inference): distinguish Gemini catalog shapes --- docs/inference/use-google-gemini.mdx | 3 +- src/lib/inference/provider-models.test.ts | 46 +++++++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/inference/use-google-gemini.mdx b/docs/inference/use-google-gemini.mdx index 7b9eca00462..1676d208b56 100644 --- a/docs/inference/use-google-gemini.mdx +++ b/docs/inference/use-google-gemini.mdx @@ -57,11 +57,12 @@ Model validation can fail with these messages: Verify `GEMINI_API_KEY`, host access to `generativelanguage.googleapis.com`, and the reported response. - `Model '' is not available from Google Gemini. Checked https://generativelanguage.googleapis.com/v1beta/models.` The catalog did not contain the model ID. + This message also appears when the catalog omits `models`, because NemoClaw treats the response as an empty catalog. Check the ID for typing errors. Custom IDs can include or omit the `models/` prefix. Embedding-only models do not appear because they do not support `generateContent`. - `Unexpected Gemini model catalog response: expected a top-level models array` - The Google model catalog returned JSON with the wrong shape. + The Google model catalog returned a `models` value that is not an array. Retry the request, then inspect the Google service or proxy response if the error continues. - `Gemini model catalog pagination repeated page token ''` The catalog repeated a `nextPageToken`, so NemoClaw stopped reading pages. diff --git a/src/lib/inference/provider-models.test.ts b/src/lib/inference/provider-models.test.ts index aa5913173c4..1f936846382 100644 --- a/src/lib/inference/provider-models.test.ts +++ b/src/lib/inference/provider-models.test.ts @@ -266,6 +266,52 @@ describe("provider model helpers", () => { }); }); + it("reports an unavailable Gemini model when the catalog omits models (#8971)", () => { + const result = validateOpenAiLikeModel( + "Google Gemini", + "https://generativelanguage.googleapis.com/v1beta/openai/", + "gemini-2.5-flash", + "AIzaFakeKey123", + { + runCurlProbeImpl: () => ({ + ok: true, + httpStatus: 200, + curlStatus: 0, + body: JSON.stringify({}), + stderr: "", + message: "", + }), + }, + ); + + expect(result).toEqual({ + ok: false, + httpStatus: 200, + curlStatus: 0, + message: `Model 'gemini-2.5-flash' is not available from Google Gemini. Checked ${GEMINI_NATIVE_MODELS_ENDPOINT_URL}.`, + }); + }); + + it("rejects a Gemini catalog whose models value is not an array (#8971)", () => { + const result = fetchGeminiModels("AIzaFakeKey123", { + runCurlProbeImpl: () => ({ + ok: true, + httpStatus: 200, + curlStatus: 0, + body: JSON.stringify({ models: {} }), + stderr: "", + message: "", + }), + }); + + expect(result).toEqual({ + ok: false, + httpStatus: 200, + curlStatus: 0, + message: "Unexpected Gemini model catalog response: expected a top-level models array", + }); + }); + it("fails Gemini native catalog pagination after the bounded page budget (#6975)", () => { const requestedUrls: string[] = []; From fcf909e0d356d7ae66cc22109549c644ed067e11 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 14 Aug 2026 20:54:36 -0700 Subject: [PATCH 5/5] docs(inference): distinguish null Gemini catalog models --- docs/inference/use-google-gemini.mdx | 2 +- src/lib/inference/provider-models.test.ts | 26 +++++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/inference/use-google-gemini.mdx b/docs/inference/use-google-gemini.mdx index 1676d208b56..d08e94750db 100644 --- a/docs/inference/use-google-gemini.mdx +++ b/docs/inference/use-google-gemini.mdx @@ -62,7 +62,7 @@ Model validation can fail with these messages: Custom IDs can include or omit the `models/` prefix. Embedding-only models do not appear because they do not support `generateContent`. - `Unexpected Gemini model catalog response: expected a top-level models array` - The Google model catalog returned a `models` value that is not an array. + The Google model catalog returned a non-null `models` value that is not an array. Retry the request, then inspect the Google service or proxy response if the error continues. - `Gemini model catalog pagination repeated page token ''` The catalog repeated a `nextPageToken`, so NemoClaw stopped reading pages. diff --git a/src/lib/inference/provider-models.test.ts b/src/lib/inference/provider-models.test.ts index 1f936846382..280b3c4ec37 100644 --- a/src/lib/inference/provider-models.test.ts +++ b/src/lib/inference/provider-models.test.ts @@ -292,6 +292,32 @@ describe("provider model helpers", () => { }); }); + it("reports an unavailable Gemini model when the catalog models value is null (#8971)", () => { + const result = validateOpenAiLikeModel( + "Google Gemini", + "https://generativelanguage.googleapis.com/v1beta/openai/", + "gemini-2.5-flash", + "AIzaFakeKey123", + { + runCurlProbeImpl: () => ({ + ok: true, + httpStatus: 200, + curlStatus: 0, + body: JSON.stringify({ models: null }), + stderr: "", + message: "", + }), + }, + ); + + expect(result).toEqual({ + ok: false, + httpStatus: 200, + curlStatus: 0, + message: `Model 'gemini-2.5-flash' is not available from Google Gemini. Checked ${GEMINI_NATIVE_MODELS_ENDPOINT_URL}.`, + }); + }); + it("rejects a Gemini catalog whose models value is not an array (#8971)", () => { const result = fetchGeminiModels("AIzaFakeKey123", { runCurlProbeImpl: () => ({