Robust Error Handling

[jerop]

Problem

Currently, Gemini CLI exits with code 0 for most scenarios, including some failure conditions like hitting maxSessionTurns. This makes it difficult for downstream consumers (like GitHub Actions and other automations) to programmatically distinguish between different types of failures and handle them appropriately. Learn more in google-github-actions/run-gemini-cli#217.

Solution

Implement standardized error messages or exit codes that allow consumers to programmatically handle different failure scenarios, for example:

1. Success (operation completed successfully)
2. General failure (catch-all for unspecified errors)
3. Authentication failure (invalid API keys, token issues)
4. Rate limit exceeded (API quota or rate limiting)
5. Session limit reached (maxSessionTurns exceeded)
6. Network/connectivity issues (timeouts, etc.)
7. Invalid configuration (malformed settings.json, invalid parameters)
8. Permission denied (insufficient access rights)
9. Resource not found (invalid model, missing files)
10. Input validation error (invalid prompt, malformed input)

@leehagoodjames @sethvargo as discussed in google-github-actions/run-gemini-cli#206 (comment)

cc @jacob314 @bdmorgan

[sethvargo]

I agree this would be super useful. Even if we cannot prioritize unique exit codes right now, ensuring we exit non-zero on failure would be a huge improvement.

For examples of other tools that do this really well, see https://curl.se/libcurl/c/libcurl-errors.html. My offer:

• 0 - Success
• 1 - General failure
• 41 - Authentication failure
• 49 - Rate limit exceeded
• 53 - maxSessionTurns exceeded
• 50 - Network/connectivity issues
• 52 - Invalid configuration (matches most unix commands)
• 43 - Permission denied (insufficient access rights)
• 44 - Resource not found (invalid model, missing files)
• 42 - Input validation error (invalid prompt, malformed input)
• 1 - Anything else

(Those are the HTTP errors with the middle digit removed)

[cornmander]

I would consider the broader problem. We lack input and output schema. Having a complicated set of configuration options (inputs) and a scarcity of outputs is downstream of that. If we have an SDK it'd likely be a better choice here than trying to make gemini-cli work like a unix utility.

[jerop]

@cornmander agree that it'd be great to have an SDK to handle all this, but the timelines for this is unclear - @NTaylorMullen please advise here on SDK plans 🙏🏾

#2023