Troubleshooting Gemini CLI errors involves several systematic approaches, starting with the built-in debugging features and comprehensive documentation. When you encounter issues, the first step is to enable debug mode using the -d or --debug flag when launching Gemini CLI. This provides verbose output that shows detailed information about what the CLI is doing behind the scenes, including file operations, API calls, and internal processes. The debug output helps identify exactly where problems occur and provides context about the CLI’s decision-making process, making it easier to understand the root cause of issues.
Common troubleshooting scenarios include authentication problems, model switching issues, and MCP server connectivity problems. For authentication errors like “Failed to login” or “Request contains an invalid argument,” the solution often involves checking your authentication method, ensuring proper API key configuration, or switching to a different authentication approach. Users with Google Workspace accounts may need to set the GOOGLE_CLOUD_PROJECT environment variable or use API keys from AI Studio instead of OAuth authentication. For model-related issues where the CLI automatically switches from Pro to Flash models, the problem typically stems from quota limitations in the free tier, and can be resolved by upgrading to a paid API key or adjusting usage patterns.
The official troubleshooting guide provides detailed solutions for specific error scenarios, including EADDRINUSE errors for MCP servers, command not found errors, and various configuration issues. For complex problems, Gemini CLI includes a /bug command that allows you to report issues directly to the development team with detailed context about what you were trying to accomplish. When troubleshooting MCP server issues, check the server console output for error messages, verify port availability, and ensure proper configuration in your settings.json file. The CLI also provides various diagnostic commands like /stats for session information and /mcp for checking MCP server connectivity status. If issues persist, the open-source nature of the project means you can examine the source code, file issues on GitHub, and benefit from community support and contributions.