Repository navigation
docs: add common troubleshooting guidance to the Python quickstart #2399
Description
Documentation enhancement: add common troubleshooting guidance to the Python quickstart
Problem
The Python quickstart clearly explains installation, API-key setup, and running an agent, but it does not include guidance for common first-run failures.
As a new ADK user, I encountered errors such as:
503 UNAVAILABLEwhen a model was temporarily at capacity- API quota or billing-limit errors
CERTIFICATE_VERIFY_FAILEDwhile connecting to the Gemini API
Without a brief troubleshooting section, it is difficult to tell whether these errors come from agent code, local Python setup, API configuration, or temporary service availability.
Proposed change
Add a concise Troubleshooting section near the end of the Python quickstart that covers:
| Symptom | Likely cause | Suggested next step |
|---|---|---|
503 UNAVAILABLE / high demand |
Temporary model-service capacity issue | Wait briefly and retry; optionally try another supported model if it persists |
| Quota or billing error | The Google AI project has no available quota for the request | Check the project’s usage tier, quota, and billing configuration in Google AI Studio |
CERTIFICATE_VERIFY_FAILED |
Python cannot locate a trusted CA certificate bundle | Verify the active Python environment and configure a valid certificate bundle, such as certifi where appropriate |
| API key appears in a log or screenshot | Sensitive credential exposure | Revoke/rotate the key and redact credentials before sharing logs |
Include a short reminder: never paste API keys into logs, screenshots, issues, or pull requests.
Scope
- Documentation-only change in
docs/get-started/python.md - Keep the section short and beginner-focused
- Link to authoritative Gemini quota/billing documentation instead of duplicating detailed billing guidance
- Do not change agent code or runtime behavior
Why this is useful
This would help new users quickly distinguish temporary API issues from local setup problems and reduce confusion during their first ADK project.
I’d be happy to contribute a focused documentation PR for this.
Activity
snehal1931 commentedon Oct 14, 2026
Hi! I'd like to contribute to this issue. I'll review the existing Python quickstart and contributing guidelines, then prepare a focused documentation update covering the proposed troubleshooting cases. I'll also verify the documentation links and follow the repository's contribution requirements. Thanks!
GouthamiN25 commentedon Oct 14, 2026
Thanks for your interest, @snehal1931 . I opened this issue and intend to prepare the focused documentation PR myself based on the first-run errors I encountered.
To avoid duplicate effort, I’ll post progress and link the PR here. Could a maintainer please assign this issue to me if appropriate?
snehal1931 commentedon Oct 14, 2026
Thanks for letting me know! I understand and will avoid duplicating your work. I'll keep an eye on the issue and would be happy to help with any other improvements if needed.