BoundaryML/baml · error

options.project_id is required when using API key auth with

Error message

options.project_id is required when using API key auth with Vertex 'location' URLs;

What it means

When building the Vertex AI request URL on a regional '<location>-aiplatform.googleapis.com' endpoint, the project ID is required. If project_id is absent from options AND an API key is being used as a query parameter, BAML bails because it cannot construct a valid regional URL (and will not fall back to Application Default Credentials when an API key is present).

Source

Thrown at engine/baml-runtime/src/internal/llm_client/primitive/vertex/vertex_client.rs:265

        _expose_secrets: bool,
    ) -> Result<reqwest::RequestBuilder> {
        // Determine if API key auth is being used (query param 'key')
        let has_api_key_query = self.properties.query_params.contains_key("key");
        let mut vertex_auth: Option<std::sync::Arc<super::auth::VertexAuth>> = None;

        let base_url = match &self.properties.base_url_or_location {
            BaseUrlOrLocation::BaseUrl(base_url) => base_url.to_string(),
            BaseUrlOrLocation::Location(location) => {
                let domain = if location == "global" {
                    "aiplatform.googleapis.com".to_string()
                } else {
                    format!("{location}-aiplatform.googleapis.com")
                };
                let project_id = match self.properties.project_id.as_ref() {
                    Some(project_id) => project_id.to_string(),
                    None => {
                        if has_api_key_query {
                            anyhow::bail!(
                                "options.project_id is required when using API key auth with Vertex 'location' URLs;"
                            );
                        }
                        // Fallback to GCP Application Default Credentials only when not using API key
                        let va = match &vertex_auth {
                            Some(va) => va,
                            None => {
                                vertex_auth = Some(
                                    super::auth::VertexAuth::get_or_create(
                                        &self.properties.auth_strategy,
                                    )
                                    .await?,
                                );
                                vertex_auth.as_ref().unwrap()
                            }
                        };
                        va.project_id().await?.to_string()
                    }

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Add project_id to the client's Vertex options (e.g. project_id "my-gcp-project")
2. Alternatively switch to Application Default Credentials / service-account auth so project_id can be inferred, though supplying it explicitly is still recommended
3. Double-check the project ID string matches the GCP project hosting the Vertex endpoint

Example fix

// before
options {
  model gemini-1.5-pro
  location us-central1
  api_key $VERTEX_API_KEY
}
// after
options {
  model gemini-1.5-pro
  location us-central1
  project_id my-gcp-project
  api_key $VERTEX_API_KEY
}

function assertVertexApiKeysConfig(options) {
  if (options?.api_key && !options?.project_id) {
    throw new Error("vertex options with api_key must also set project_id");
  }
}
assertVertexApiKeysConfig(clientConfig.options);

try {
  await baml_client.MyVertexFunction(prompt);
} catch (err) {
  if (String(err).includes('options.project_id is required')) {
    console.error('Add options.project_id to your Vertex client config');
  }
  throw err;
}

When it happens

Trigger: Using Vertex with API-key authentication (has_api_key_query true) while omitting options.project_id, on a location-based URL.

Common situations: Authenticating to Vertex with an API key (instead of service-account credentials) but forgetting to set project_id in the client options; works without project_id when using ADC but fails once an API key is switched on.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Failed to auth - system_default strategy did not resolve suc
• Invalid client property. Should have been a vertex property
• Failed to load GCP creds project ID (failed to resolve): try
• LLM client '{client_name}' requires environment variable '{k
• No source root contains {}

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/1e9cb604230f029b. Report an issue: GitHub.