eyaltoledano/claude-task-master · critical · VertexConfigError

Google Cloud project ID is required for Vertex AI. Set VERTE

Error message

Google Cloud project ID is required for Vertex AI. Set VERTEX_PROJECT_ID environment variable.

What it means

Vertex AI requires a Google Cloud project ID to route requests. GoogleVertexProvider.validateAuth throws VertexConfigError when projectId is missing or an empty/whitespace string. The project ID normally comes from the VERTEX_PROJECT_ID environment variable.

Source

Thrown at src/ai-providers/google-vertex.js:106

		// Check for API key OR service account credentials
		const hasValidApiKey = this.isValidCredential(apiKey);
		const hasValidCredentials = this.isValidCredential(credentials);

		if (!hasValidApiKey && !hasValidCredentials) {
			throw new VertexAuthError(
				'Vertex AI requires authentication. Provide one of the following:\n' +
					'  • GOOGLE_API_KEY environment variable (typical for API-based auth), OR\n' +
					'  • GOOGLE_APPLICATION_CREDENTIALS pointing to a service account JSON file (recommended for production)'
			);
		}

		// Project ID is required for Vertex AI
		if (
			!projectId ||
			(typeof projectId === 'string' && projectId.trim().length === 0)
		) {
			throw new VertexConfigError(
				'Google Cloud project ID is required for Vertex AI. Set VERTEX_PROJECT_ID environment variable.'
			);
		}

		// Location is required for Vertex AI
		if (
			!location ||
			(typeof location === 'string' && location.trim().length === 0)
		) {
			throw new VertexConfigError(
				'Google Cloud location is required for Vertex AI. Set VERTEX_LOCATION environment variable (e.g., "us-central1").'
			);
		}
	}

	/**
	 * Creates and returns a Google Vertex AI client instance.
	 * @param {object} params - Parameters for client initialization

View on GitHub (pinned to c0c98d367c)

Solutions

Set VERTEX_PROJECT_ID in the environment (e.g. export VERTEX_PROJECT_ID=my-gcp-project)
Add VERTEX_PROJECT_ID to your .env file and ensure it is loaded
Verify no empty-string default overwrites the env var in config code
Confirm the project ID exists and the Vertex AI API is enabled in that project

Example fix

// before
# .env
GOOGLE_API_KEY=...
// after
# .env
GOOGLE_API_KEY=...
VERTEX_PROJECT_ID=my-gcp-project

Defensive patterns

Strategy: validation

Validate before calling

function assertVertexProjectId() {
  const projectId = process.env.VERTEX_PROJECT_ID;
  if (!projectId || projectId.trim().length === 0) {
    throw new Error('VERTEX_PROJECT_ID must be set to a Google Cloud project ID');
  }
}

Type guard

null

Try / catch

try {
  await vertexProvider.generateText({ messages, modelId });
} catch (e) {
  if (e.name === 'VertexConfigError' || /project ID is required for Vertex AI/.test(e.message)) {
    console.error('Set VERTEX_PROJECT_ID in this environment');
  } else throw e;
}

Prevention

Add VERTEX_PROJECT_ID to .env templates and document it in setup docs
Run an env-var preflight (project + location + auth) at startup
Ensure .env files are loaded and copied into CI/container environments

When it happens

Trigger: Using the Vertex provider with VERTEX_PROJECT_ID unset or set to ''/whitespace, or a projectId param passed as an empty string.

Common situations: Deploying to a new environment (CI, container, serverless) where only the API key was copied over; forgetting to add VERTEX_PROJECT_ID to .env; project variable shadowed by an empty default in config loading.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/f1ec4b3dd7030aa4. Report an issue: GitHub.