feat: better error messages (#20577)

Co-authored-by: Gal Zahavi <38544478+galz10@users.noreply.github.com>
# Conflicts:
#	packages/cli/src/test-utils/render.tsx
#	packages/cli/src/ui/AppContainer.tsx
#	packages/cli/src/ui/contexts/UIActionsContext.tsx
#	packages/core/src/utils/errors.test.ts
#	packages/core/src/utils/errors.ts

packages/cli/src/ui/AppContainer.tsx

@@ -625,7 +625,14 @@ export const AppContainer = (props: AppContainerProps) => {
     onAuthError,
     apiKeyDefaultValue,
     reloadApiKey,
-  } = useAuthCommand(settings, config, initializationResult.authError);
+    accountSuspensionInfo,
+    setAccountSuspensionInfo,
+  } = useAuthCommand(
+    settings,
+    config,
+    initializationResult.authError,
+    initializationResult.accountSuspensionInfo,
+  );
   const [authContext, setAuthContext] = useState<{ requiresRestart?: boolean }>(
     {},
   );
@@ -1977,6 +1984,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       isAuthenticating,
       isConfigInitialized,
       authError,
+      accountSuspensionInfo,
       isAuthDialogOpen,
       isAwaitingApiKeyInput: authState === AuthState.AwaitingApiKeyInput,
       apiKeyDefaultValue,
@@ -2094,6 +2102,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       isAuthenticating,
       isConfigInitialized,
       authError,
+      accountSuspensionInfo,
       isAuthDialogOpen,
       editorError,
       isEditorDialogOpen,
@@ -2288,6 +2297,14 @@ Logging in with Google... Restarting Gemini CLI to continue.
         }
         setNewAgents(null);
       },
+<<<<<<< HEAD
+=======
+      getPreferredEditor,
+      clearAccountSuspension: () => {
+        setAccountSuspensionInfo(null);
+        setAuthState(AuthState.Updating);
+      },
+>>>>>>> ea48bd941 (feat: better error messages (#20577))
     }),
     [
       handleThemeSelect,
@@ -2335,6 +2352,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       setActiveBackgroundShellPid,
       setIsBackgroundShellListOpen,
       setAuthContext,
+      setAccountSuspensionInfo,
       newAgents,
       config,
       historyManager,

packages/cli/src/ui/auth/BannedAccountDialog.test.tsx

@@ -0,0 +1,241 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { renderWithProviders } from '../../test-utils/render.js';
+import { waitFor } from '../../test-utils/async.js';
+import { BannedAccountDialog } from './BannedAccountDialog.js';
+import { RadioButtonSelect } from '../components/shared/RadioButtonSelect.js';
+import { useKeypress } from '../hooks/useKeypress.js';
+import {
+  openBrowserSecurely,
+  shouldLaunchBrowser,
+} from '@google/gemini-cli-core';
+import { Text } from 'ink';
+import { runExitCleanup } from '../../utils/cleanup.js';
+import type { AccountSuspensionInfo } from '../contexts/UIStateContext.js';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    openBrowserSecurely: vi.fn(),
+    shouldLaunchBrowser: vi.fn().mockReturnValue(true),
+  };
+});
+
+vi.mock('../../utils/cleanup.js', () => ({
+  runExitCleanup: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../hooks/useKeypress.js', () => ({
+  useKeypress: vi.fn(),
+}));
+
+vi.mock('../components/shared/RadioButtonSelect.js', () => ({
+  RadioButtonSelect: vi.fn(({ items }) => (
+    <>
+      {items.map((item: { value: string; label: string }) => (
+        <Text key={item.value}>{item.label}</Text>
+      ))}
+    </>
+  )),
+}));
+
+const mockedRadioButtonSelect = RadioButtonSelect as Mock;
+const mockedUseKeypress = useKeypress as Mock;
+const mockedOpenBrowser = openBrowserSecurely as Mock;
+const mockedShouldLaunchBrowser = shouldLaunchBrowser as Mock;
+const mockedRunExitCleanup = runExitCleanup as Mock;
+
+const DEFAULT_SUSPENSION_INFO: AccountSuspensionInfo = {
+  message:
+    'This service has been disabled in this account for violation of Terms of Service. Please submit an appeal to continue using this product.',
+  appealUrl: 'https://example.com/appeal',
+  appealLinkText: 'Appeal Here',
+};
+
+describe('BannedAccountDialog', () => {
+  let onExit: Mock;
+  let onChangeAuth: Mock;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    mockedShouldLaunchBrowser.mockReturnValue(true);
+    mockedOpenBrowser.mockResolvedValue(undefined);
+    mockedRunExitCleanup.mockResolvedValue(undefined);
+    onExit = vi.fn();
+    onChangeAuth = vi.fn();
+  });
+
+  it('renders the suspension message from accountSuspensionInfo', async () => {
+    const { lastFrame, waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={DEFAULT_SUSPENSION_INFO}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const frame = lastFrame();
+    expect(frame).toContain('Account Suspended');
+    expect(frame).toContain('violation of Terms of Service');
+    expect(frame).toContain('Escape to exit');
+    unmount();
+  });
+
+  it('renders menu options with appeal link text from response', async () => {
+    const { waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={DEFAULT_SUSPENSION_INFO}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const items = mockedRadioButtonSelect.mock.calls[0][0].items;
+    expect(items).toHaveLength(3);
+    expect(items[0].label).toBe('Appeal Here');
+    expect(items[1].label).toBe('Change authentication');
+    expect(items[2].label).toBe('Exit');
+    unmount();
+  });
+
+  it('hides form option when no appealUrl is provided', async () => {
+    const infoWithoutUrl: AccountSuspensionInfo = {
+      message: 'Account suspended.',
+    };
+    const { waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={infoWithoutUrl}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const items = mockedRadioButtonSelect.mock.calls[0][0].items;
+    expect(items).toHaveLength(2);
+    expect(items[0].label).toBe('Change authentication');
+    expect(items[1].label).toBe('Exit');
+    unmount();
+  });
+
+  it('uses default label when appealLinkText is not provided', async () => {
+    const infoWithoutLinkText: AccountSuspensionInfo = {
+      message: 'Account suspended.',
+      appealUrl: 'https://example.com/appeal',
+    };
+    const { waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={infoWithoutLinkText}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const items = mockedRadioButtonSelect.mock.calls[0][0].items;
+    expect(items[0].label).toBe('Open the Google Form');
+    unmount();
+  });
+
+  it('opens browser when appeal option is selected', async () => {
+    const { waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={DEFAULT_SUSPENSION_INFO}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const { onSelect } = mockedRadioButtonSelect.mock.calls[0][0];
+    await onSelect('open_form');
+    expect(mockedOpenBrowser).toHaveBeenCalledWith(
+      'https://example.com/appeal',
+    );
+    expect(onExit).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it('shows URL when browser cannot be launched', async () => {
+    mockedShouldLaunchBrowser.mockReturnValue(false);
+    const { lastFrame, waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={DEFAULT_SUSPENSION_INFO}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const { onSelect } = mockedRadioButtonSelect.mock.calls[0][0];
+    onSelect('open_form');
+    await waitFor(() => {
+      expect(lastFrame()).toContain('Please open this URL in a browser');
+    });
+    expect(mockedOpenBrowser).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it('calls onExit when "Exit" is selected', async () => {
+    const { waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={DEFAULT_SUSPENSION_INFO}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const { onSelect } = mockedRadioButtonSelect.mock.calls[0][0];
+    await onSelect('exit');
+    expect(mockedRunExitCleanup).toHaveBeenCalled();
+    expect(onExit).toHaveBeenCalled();
+    unmount();
+  });
+
+  it('calls onChangeAuth when "Change authentication" is selected', async () => {
+    const { waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={DEFAULT_SUSPENSION_INFO}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const { onSelect } = mockedRadioButtonSelect.mock.calls[0][0];
+    onSelect('change_auth');
+    expect(onChangeAuth).toHaveBeenCalled();
+    expect(onExit).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it('exits on escape key', async () => {
+    const { waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={DEFAULT_SUSPENSION_INFO}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    const keypressHandler = mockedUseKeypress.mock.calls[0][0];
+    const result = keypressHandler({ name: 'escape' });
+    expect(result).toBe(true);
+    unmount();
+  });
+
+  it('renders snapshot correctly', async () => {
+    const { lastFrame, waitUntilReady, unmount } = renderWithProviders(
+      <BannedAccountDialog
+        accountSuspensionInfo={DEFAULT_SUSPENSION_INFO}
+        onExit={onExit}
+        onChangeAuth={onChangeAuth}
+      />,
+    );
+    await waitUntilReady();
+    expect(lastFrame()).toMatchSnapshot();
+    unmount();
+  });
+});

packages/cli/src/ui/auth/BannedAccountDialog.tsx

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { useCallback, useMemo, useState } from 'react';
+import { Box, Text } from 'ink';
+import { theme } from '../semantic-colors.js';
+import { RadioButtonSelect } from '../components/shared/RadioButtonSelect.js';
+import { useKeypress } from '../hooks/useKeypress.js';
+import {
+  openBrowserSecurely,
+  shouldLaunchBrowser,
+} from '@google/gemini-cli-core';
+import { runExitCleanup } from '../../utils/cleanup.js';
+import type { AccountSuspensionInfo } from '../contexts/UIStateContext.js';
+
+interface BannedAccountDialogProps {
+  accountSuspensionInfo: AccountSuspensionInfo;
+  onExit: () => void;
+  onChangeAuth: () => void;
+}
+
+export function BannedAccountDialog({
+  accountSuspensionInfo,
+  onExit,
+  onChangeAuth,
+}: BannedAccountDialogProps): React.JSX.Element {
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  const appealUrl = accountSuspensionInfo.appealUrl;
+  const appealLinkText =
+    accountSuspensionInfo.appealLinkText ?? 'Open the Google Form';
+
+  const items = useMemo(() => {
+    const menuItems = [];
+    if (appealUrl) {
+      menuItems.push({
+        label: appealLinkText,
+        value: 'open_form' as const,
+        key: 'open_form',
+      });
+    }
+    menuItems.push(
+      {
+        label: 'Change authentication',
+        value: 'change_auth' as const,
+        key: 'change_auth',
+      },
+      {
+        label: 'Exit',
+        value: 'exit' as const,
+        key: 'exit',
+      },
+    );
+    return menuItems;
+  }, [appealUrl, appealLinkText]);
+
+  useKeypress(
+    (key) => {
+      if (key.name === 'escape') {
+        void handleExit();
+        return true;
+      }
+      return false;
+    },
+    { isActive: true },
+  );
+
+  const handleExit = useCallback(async () => {
+    await runExitCleanup();
+    onExit();
+  }, [onExit]);
+
+  const handleSelect = useCallback(
+    async (choice: string) => {
+      if (choice === 'open_form' && appealUrl) {
+        if (!shouldLaunchBrowser()) {
+          setErrorMessage(`Please open this URL in a browser: ${appealUrl}`);
+          return;
+        }
+
+        try {
+          await openBrowserSecurely(appealUrl);
+        } catch {
+          setErrorMessage(`Failed to open browser. Please visit: ${appealUrl}`);
+        }
+      } else if (choice === 'change_auth') {
+        onChangeAuth();
+      } else {
+        await handleExit();
+      }
+    },
+    [handleExit, onChangeAuth, appealUrl],
+  );
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text bold color={theme.status.error}>
+        Error: Account Suspended
+      </Text>
+
+      <Box marginTop={1}>
+        <Text>{accountSuspensionInfo.message}</Text>
+      </Box>
+
+      {appealUrl && (
+        <>
+          <Box marginTop={1}>
+            <Text>Appeal URL:</Text>
+          </Box>
+          <Box>
+            <Text color={theme.text.link}>[{appealUrl}]</Text>
+          </Box>
+        </>
+      )}
+
+      {errorMessage && (
+        <Box marginTop={1}>
+          <Text color={theme.status.error}>{errorMessage}</Text>
+        </Box>
+      )}
+
+      <Box marginTop={1}>
+        <RadioButtonSelect
+          items={items}
+          onSelect={(choice) => void handleSelect(choice)}
+        />
+      </Box>
+
+      <Box marginTop={1}>
+        <Text dimColor>Escape to exit</Text>
+      </Box>
+    </Box>
+  );
+}

packages/cli/src/ui/auth/__snapshots__/BannedAccountDialog.test.tsx.snap

@@ -0,0 +1,17 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`BannedAccountDialog > renders snapshot correctly 1`] = `
+"
+ Error: Account Suspended
+
+ This service has been disabled in this account for violation of Terms of Service. Please submit an
+ appeal to continue using this product.
+
+ Appeal URL:
+ [https://example.com/appeal]
+
+ Appeal HereChange authenticationExit
+
+ Escape to exit
+"
+`;

packages/cli/src/ui/auth/useAuth.ts

@@ -11,6 +11,7 @@ import {
   type Config,
   loadApiKey,
   debugLogger,
+  isAccountSuspendedError,
 } from '@google/gemini-cli-core';
 import { getErrorMessage } from '@google/gemini-cli-core';
 import { AuthState } from '../types.js';
@@ -34,16 +35,21 @@ export function validateAuthMethodWithSettings(
   return validateAuthMethod(authType);
 }
 
+import type { AccountSuspensionInfo } from '../contexts/UIStateContext.js';
+
 export const useAuthCommand = (
   settings: LoadedSettings,
   config: Config,
   initialAuthError: string | null = null,
+  initialAccountSuspensionInfo: AccountSuspensionInfo | null = null,
 ) => {
   const [authState, setAuthState] = useState<AuthState>(
     initialAuthError ? AuthState.Updating : AuthState.Unauthenticated,
   );
 
   const [authError, setAuthError] = useState<string | null>(initialAuthError);
+  const [accountSuspensionInfo, setAccountSuspensionInfo] =
+    useState<AccountSuspensionInfo | null>(initialAccountSuspensionInfo);
   const [apiKeyDefaultValue, setApiKeyDefaultValue] = useState<
     string | undefined
   >(undefined);
@@ -130,7 +136,16 @@ export const useAuthCommand = (
         setAuthError(null);
         setAuthState(AuthState.Authenticated);
       } catch (e) {
-        onAuthError(`Failed to login. Message: ${getErrorMessage(e)}`);
+        const suspendedError = isAccountSuspendedError(e);
+        if (suspendedError) {
+          setAccountSuspensionInfo({
+            message: suspendedError.message,
+            appealUrl: suspendedError.appealUrl,
+            appealLinkText: suspendedError.appealLinkText,
+          });
+        } else {
+          onAuthError(`Failed to login. Message: ${getErrorMessage(e)}`);
+        }
       }
     })();
   }, [
@@ -150,5 +165,7 @@ export const useAuthCommand = (
     onAuthError,
     apiKeyDefaultValue,
     reloadApiKey,
+    accountSuspensionInfo,
+    setAccountSuspensionInfo,
   };
 };

packages/cli/src/ui/components/DialogManager.tsx

@@ -13,6 +13,7 @@ import { ThemeDialog } from './ThemeDialog.js';
 import { SettingsDialog } from './SettingsDialog.js';
 import { AuthInProgress } from '../auth/AuthInProgress.js';
 import { AuthDialog } from '../auth/AuthDialog.js';
+import { BannedAccountDialog } from '../auth/BannedAccountDialog.js';
 import { ApiAuthDialog } from '../auth/ApiAuthDialog.js';
 import { EditorSettingsDialog } from './EditorSettingsDialog.js';
 import { PrivacyNotice } from '../privacy/PrivacyNotice.js';
@@ -284,6 +285,21 @@ export const DialogManager = ({
       </Box>
     );
   }
+  if (uiState.accountSuspensionInfo) {
+    return (
+      <Box flexDirection="column">
+        <BannedAccountDialog
+          accountSuspensionInfo={uiState.accountSuspensionInfo}
+          onExit={() => {
+            process.exit(1);
+          }}
+          onChangeAuth={() => {
+            uiActions.clearAccountSuspension();
+          }}
+        />
+      </Box>
+    );
+  }
   if (uiState.isAuthenticating) {
     return (
       <AuthInProgress
@@ -306,6 +322,7 @@ export const DialogManager = ({
       </Box>
     );
   }
+
   if (uiState.isAuthDialogOpen) {
     return (
       <Box flexDirection="column">

packages/cli/src/ui/contexts/UIActionsContext.tsx

@@ -82,6 +82,11 @@ export interface UIActions {
   setAuthContext: (context: { requiresRestart?: boolean }) => void;
   handleRestart: () => void;
   handleNewAgentsSelect: (choice: NewAgentsChoice) => Promise<void>;
+<<<<<<< HEAD
+=======
+  getPreferredEditor: () => EditorType | undefined;
+  clearAccountSuspension: () => void;
+>>>>>>> ea48bd941 (feat: better error messages (#20577))
 }
 
 export const UIActionsContext = createContext<UIActions | null>(null);

packages/cli/src/ui/contexts/UIStateContext.tsx

@@ -62,6 +62,12 @@ export interface QuotaState {
   validationRequest: ValidationDialogRequest | null;
 }
 
+export interface AccountSuspensionInfo {
+  message: string;
+  appealUrl?: string;
+  appealLinkText?: string;
+}
+
 export interface UIState {
   history: HistoryItem[];
   historyManager: UseHistoryManagerReturn;
@@ -72,6 +78,7 @@ export interface UIState {
   isAuthenticating: boolean;
   isConfigInitialized: boolean;
   authError: string | null;
+  accountSuspensionInfo: AccountSuspensionInfo | null;
   isAuthDialogOpen: boolean;
   isAwaitingApiKeyInput: boolean;
   apiKeyDefaultValue?: string;