Gemini troubleshooting
Gemini and OpenAI compatible interfaces are not the same thing. Only configure according to Gemini if the provider explicitly provides Gemini / Google / Vertex related interfaces, or the tutorial clearly states support for Gemini CLI.
What should be confirmed first?
| Check items | How to view | Why |
|---|---|---|
| Target Tool | Confirm you are troubleshooting Gemini CLI | The authentication method for Gemini CLI is different from Codex and Claude Code |
| The provider supports Gemini | There are entries related to Gemini / Google / Vertex in the backend or tutorials | OpenAI compatible interface is not the same as the Gemini interface |
| Key Type | Use the corresponding Key for Gemini or Vertex | If the Key type is incorrect, you may get 401, 403, or be repeatedly asked to log in |
| Model Name | Fill in according to the Gemini model list | Do not enter OpenAI or Claude model names in Gemini |
Common errors
| Phenomenon | Priority check | Solutions |
|---|---|---|
| Still prompts to log in to Google | Gemini CLI self-authentication | First complete the authentication required as prompted by Gemini CLI; the provider configuration cannot replace the login process required by the target tool itself. |
| 401 / 403 | Gemini Key or permissions | Confirm that the Key belongs to the Gemini / Google / Vertex group, and that the current project or account has permissions for the corresponding model. |
| 404 / model not found | Gemini model name | Fill in according to the Gemini model list in the provider’s backend; do not enter OpenAI or Claude model names. |
| Connection failed | Gemini Base URL | Do not enter the regular OpenAI-compatible Base URL in Gemini; only configure it when the backend explicitly states support for Gemini. |
| No change after switching CC-Switch | Target tool and terminal status | Confirm that the application target is Gemini CLI, save, then reopen the terminal and test again. |
Minimal test
First confirm that Gemini CLI can return a fixed short sentence, then continue troubleshooting more complex tasks.
Gemini minimal test
gemini "Please reply only: Gemini configuration test successful"Feedback template
When giving feedback to the provider, write like this
Tool: Gemini System version: Provider dashboard Base URL: Model ID / model name: Exact error: I have checked: no spaces in the Key / balance is sufficient / model name copied exactly / Base URL copied from the dashboard / terminal reopened