diff --git a/packages/core/src/code_assist/setup.test.ts b/packages/core/src/code_assist/setup.test.ts
index cf2251ed13..6779143b9a 100644
--- a/packages/core/src/code_assist/setup.test.ts
+++ b/packages/core/src/code_assist/setup.test.ts
@@ -8,6 +8,7 @@ import {
   ProjectIdRequiredError,
   setupUser,
   ValidationCancelledError,
+  InvalidNumericProjectIdError,
   resetUserDataCacheForTesting,
 } from './setup.js';
 import { ValidationRequiredError } from '../utils/googleQuotaErrors.js';
@@ -218,6 +219,20 @@ describe('setupUser', () => {
         ProjectIdRequiredError,
       );
     });
+
+    it('should throw InvalidNumericProjectIdError when GOOGLE_CLOUD_PROJECT is numeric', async () => {
+      vi.stubEnv('GOOGLE_CLOUD_PROJECT', '1234567890');
+      await expect(setupUser({} as OAuth2Client, mockConfig)).rejects.toThrow(
+        InvalidNumericProjectIdError,
+      );
+    });
+
+    it('should throw InvalidNumericProjectIdError when GOOGLE_CLOUD_PROJECT_ID is numeric', async () => {
+      vi.stubEnv('GOOGLE_CLOUD_PROJECT_ID', '1234567890');
+      await expect(setupUser({} as OAuth2Client, mockConfig)).rejects.toThrow(
+        InvalidNumericProjectIdError,
+      );
+    });
   });
 
   describe('new user', () => {
diff --git a/packages/core/src/code_assist/setup.ts b/packages/core/src/code_assist/setup.ts
index a68a1ec550..6d4cbfd9c0 100644
--- a/packages/core/src/code_assist/setup.ts
+++ b/packages/core/src/code_assist/setup.ts
@@ -36,6 +36,15 @@ export class ProjectIdRequiredError extends Error {
   }
 }
 
+export class InvalidNumericProjectIdError extends Error {
+  constructor(projectId: string) {
+    super(
+      `Invalid Google Cloud Project ID: "${projectId}". The GOOGLE_CLOUD_PROJECT (or GOOGLE_CLOUD_PROJECT_ID) environment variable must be set to your string-based Project ID (e.g., "my-project-123"), not your numeric Project Number. Please update your environment variables.`,
+    );
+    this.name = 'InvalidNumericProjectIdError';
+  }
+}
+
 /**
  * Error thrown when user cancels the validation process.
  * This is a non-recoverable error that should result in auth failure.
@@ -122,6 +131,10 @@ export async function setupUser(
     process.env['GOOGLE_CLOUD_PROJECT_ID'] ||
     undefined;
 
+  if (projectId && /^\d+$/.test(projectId)) {
+    throw new InvalidNumericProjectIdError(projectId);
+  }
+
   const projectCache = userDataCache.getOrCreate(client, () =>
     createCache<string | undefined, Promise<UserData>>({
       storage: 'map',