[DOCS] Confusing variable override logic in Google Vertex AI credentials documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/google-vertex-ai

Section/Topic

Section: 3. Configure GCP credentials, specifically the <Note> block regarding project ID environment variables.

Current Documentation

The documentation currently states:

"When authenticating, Claude Code will automatically use the project ID from the ANTHROPIC_VERTEX_PROJECT_ID environment variable. To override this, set one of these environment variables: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, or GOOGLE_APPLICATION_CREDENTIALS."

What's Wrong or Missing?

The logic described is counter-intuitive and confusing. Standard software configuration convention dictates that a specific variable (like ANTHROPIC_VERTEX_PROJECT_ID) should override a generic/system-wide variable (like GCLOUD_PROJECT).

The current phrasing ("To override this [the specific variable], set [the generic variable]") implies that the generic variable takes precedence. If a user has ANTHROPIC_VERTEX_PROJECT_ID set for Claude Code specifically, but also has GCLOUD_PROJECT set globally for other CLI tools, the documentation implies the specific Claude setting will be ignored in favor of the global one. This effectively makes the specific variable useless in a mixed environment.

It is highly likely the documentation meant to say that ANTHROPIC_VERTEX_PROJECT_ID is the override, or that it defaults to ANTHROPIC_VERTEX_PROJECT_ID and falls back to the others.

Suggested Improvement

Clarify the order of precedence. Assuming the standard behavior where the Anthropic-specific variable takes priority, the text should be rewritten to indicate fallback logic rather than override logic.

Suggested text:

"Claude Code prioritizes the project ID defined in the ANTHROPIC_VERTEX_PROJECT_ID environment variable. If this is not set, it will fall back to using GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, or the credentials defined in GOOGLE_APPLICATION_CREDENTIALS."

Note: If the current documentation is actually factually correct (that GCLOUD_PROJECT trumps the specific variable), a warning should be added explaining this non-standard behavior.

Impact

High - Prevents users from using a feature

Additional Context

In most cloud SDK integrations, specific overrides generic. For example, in AWS, a command-line --region flag overrides AWS_REGION env var, which overrides the ~/.aws/config file. The current wording suggests the inverse of this standard hierarchy.