Troubleshooting

Cause. gcloud isn't on your PATH, or the install never completed.

Fix. Reinstall the SDK and source the path file in your shell config.

curl https://sdk.cloud.google.com | bash
exec -l $SHELL
gcloud --version

Cause. You're authenticated to a project that doesn't have billing enabled, or your account lacks IAM roles.

Fix. Confirm the active project, billing, and your role:

gcloud config get-value project
gcloud projects describe $(gcloud config get-value project)
gcloud auth list

In the Cloud Console, open Billing and confirm the project is linked. In IAM & Admin, check you have at least roles/editor for the workshop work.

Cause. The required API isn't turned on for your project.

Fix. Enable the workshop APIs in one go:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  aiplatform.googleapis.com

Cause. gcloud's active project is set to something old (a personal sandbox, last week's workshop, etc.).

Fix.

gcloud config set project YOUR_PROJECT_ID

Cause. Conference Wi-Fi is rate-limiting or blocking the npm registry, or the cache is corrupted.

Fix. Switch to a hotspot, then clear the cache and retry:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Cause. An earlier dev server is still running.

Fix. Kill it or use a different port.

# find and kill it (macOS / Linux)
lsof -ti:3000 | xargs kill -9

# or run on a different port
PORT=3001 npm run dev

Cause. The folder was opened before files existed, or you're in a parent folder.

Fix. Close the folder and re-open it from the project root (the directory with package.json).

Cause. Install didn't finish, or the client was running when you added the config.

Fix. Re-run the install command, then fully quit and reopen your AI client. On macOS, "fully quit" means Cmd-Q, not just closing the window.

Cause. The local OAuth token expired or was never created.

Fix. Re-authenticate in the browser when the MCP server prompts for it. If nothing prompts, restart the server so it can trigger the auth flow again.

Cause. On a fresh project, the Cloud Build service account doesn't yet have permission to create a Cloud Run service. This is the single most common first-deploy gotcha.

Fix. Grant the roles/run.builder role to the default compute service account, then retry the deploy:

PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

Cause. One of the required APIs is off, or the enable just propagated and your CLI cached the old state.

Fix. Re-run the enable from step 1 and try again:

gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

Cause. Almost always a missing dependency in package.json or a Node version mismatch between local and Cloud Build.

Fix. Open the build log link in the failure message and read the actual error. Then either add the missing dep or pin Node:

// package.json
"engines": { "node": "20" }

Cause. Usually missing env vars (GOOGLE_CLOUD_PROJECT, LOCATION) or the service hasn't been authenticated for Vertex AI.

Fix. Check Cloud Run logs, verify env vars in the Cloud Run revision settings, and confirm gcloud auth application-default login ran on your machine before deploy.

gcloud run services logs read SERVICE_NAME --region europe-west1 --limit 50

Cause. Cloud Run injects a PORT env var (default 8080). If your server hardcodes a different port, the health check fails.

Fix. Listen on process.env.PORT:

app.listen(process.env.PORT || 3000);

Also check that your Dockerfile (if you have one) uses EXPOSE 8080 or omits EXPOSE entirely.

Cause. .env isn't being loaded, or the dev server was started before you created it.

Fix. Confirm the value is set, then restart:

cat .env
npm run dev

Cause. The service account calling Vertex AI lacks the right role.

Fix. Grant roles/aiplatform.user to the default compute service account:

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Cause. Either the model isn't available in your region, or the model name has changed since the snippet was written.

Fix. Try us-central1 as LOCATION. If that still fails, look up a current Gemini model name in the Vertex AI docs and update the model field.

Cause. Fresh projects ship with low Vertex AI quota — a handful of requests per minute.

Fix. Wait a minute between test calls. For real use, request a quota increase in the Cloud Console under IAM & Admin → Quotas.