Skip to content

An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.

fix: improve auth-related error handling (#1477)

Ralph Khreishb0199f1cfa64
diff --git a/.changeset/nine-lilies-repair.md b/.changeset/nine-lilies-repair.md
new file mode 100644
index 00000000..d1fe9b5e
--- /dev/null
+++ b/.changeset/nine-lilies-repair.md
@@ -0,0 +1,5 @@
+---
+"task-master-ai": patch
+---
+
+Improve auth-related error handling
diff --git a/apps/cli/src/utils/error-handler.ts b/apps/cli/src/utils/error-handler.ts
index 900ed796..29532691 100644
--- a/apps/cli/src/utils/error-handler.ts
+++ b/apps/cli/src/utils/error-handler.ts
@@ -3,6 +3,11 @@
* Provides consistent error formatting and debug mode detection
*/
+import {
+ AuthenticationError,
+ isSupabaseAuthError,
+ AUTH_ERROR_MESSAGES
+} from '@tm/core';
import chalk from 'chalk';
/**
@@ -36,6 +41,28 @@ export function displayError(
const sanitized = error.getSanitizedDetails();
console.error(chalk.red(`\n${sanitized.message}`));
+ // Show stack trace in debug mode or if forced
+ if ((isDebugMode() || options.forceStack) && error.stack) {
+ console.error(chalk.gray('\nStack trace:'));
+ console.error(chalk.gray(error.stack));
+ }
+ } else if (error instanceof AuthenticationError) {
+ // Handle AuthenticationError with clean message (no "Error:" prefix)
+ console.error(chalk.red(`\n${error.message}`));
+
+ // Show stack trace in debug mode or if forced
+ if ((isDebugMode() || options.forceStack) && error.stack) {
+ console.error(chalk.gray('\nStack trace:'));
+ console.error(chalk.gray(error.stack));
+ }
+ } else if (isSupabaseAuthError(error)) {
+ // Handle raw Supabase auth errors with user-friendly messages
+ const code = error.code;
+ const userMessage = code
+ ? AUTH_ERROR_MESSAGES[code] || error.message
+ : error.message;
+ console.error(chalk.red(`\n${userMessage}`));
+
// Show stack trace in debug mode or if forced
if ((isDebugMode() || options.forceStack) && error.stack) {
console.error(chalk.gray('\nStack trace:'));
diff --git a/packages/tm-core/src/index.ts b/packages/tm-core/src/index.ts
index 1c94e51f..46b4083f 100644
--- a/packages/tm-core/src/index.ts
+++ b/packages/tm-core/src/index.ts
@@ -96,6 +96,13 @@ export {
type LocalOnlyCommand
} from './modules/auth/index.js';
+// Auth error utilities (shared with CLI)
+export {
+ isSupabaseAuthError,
+ AUTH_ERROR_MESSAGES,
+ isRecoverableStaleSessionError
+} from './modules/auth/index.js';
+
// Brief types
export type { Brief } from './modules/briefs/types.js';
export type { TagWithStats } from './modules/briefs/services/brief-service.js';
diff --git a/packages/tm-core/src/modules/auth/index.ts b/packages/tm-core/src/modules/auth/index.ts
index 19b67886..437a20fb 100644
--- a/packages/tm-core/src/modules/auth/index.ts
+++ b/packages/tm-core/src/modules/auth/index.ts
@@ -38,3 +38,12 @@ export {
LOCAL_ONLY_COMMANDS,
type LocalOnlyCommand
} from './constants.js';
+
+// Auth error utilities (shared with CLI)
+export {
+ isSupabaseAuthError,
+ AUTH_ERROR_MESSAGES,
+ RECOVERABLE_STALE_SESSION_ERRORS,
+ isRecoverableStaleSessionError,
+ toAuthenticationError
+} from './utils/index.js';
diff --git a/packages/tm-core/src/modules/auth/utils/auth-error-utils.ts b/packages/tm-core/src/modules/auth/utils/auth-error-utils.ts
new file mode 100644
index 00000000..72e0e76a
--- /dev/null
+++ b/packages/tm-core/src/modules/auth/utils/auth-error-utils.ts
@@ -0,0 +1,93 @@
+/**
+ * Shared authentication error utilities
+ * These utilities are used by both tm-core (Supabase client) and CLI (error handler)
+ */
+
+import { isAuthError, type AuthError } from '@supabase/supabase-js';
+import { AuthenticationError } from '../types.js';
+
+/**
+ * Check if an error is a Supabase auth error.
+ * Uses Supabase's public isAuthError helper for stable identification.
+ */
+export function isSupabaseAuthError(
+ error: unknown
+): error is AuthError & { code?: string } {
+ return isAuthError(error);
+}
+
+/**
+ * User-friendly error messages for common Supabase auth error codes
+ * Note: refresh_token_not_found and refresh_token_already_used are expected
+ * during MFA flows and should not trigger these messages in that context.
+ */
+export const AUTH_ERROR_MESSAGES: Record<string, string> = {
+ refresh_token_not_found:
+ 'Your session has expired. Please log in again with: task-master login',
+ refresh_token_already_used:
+ 'Your session has expired (token was already used). Please log in again with: task-master login',
+ invalid_refresh_token:
+ 'Your session has expired (invalid token). Please log in again with: task-master login',
+ session_expired:
+ 'Your session has expired. Please log in again with: task-master login',
+ user_not_found:
+ 'User account not found. Please log in again with: task-master login',
+ invalid_credentials:
+ 'Invalid credentials. Please log in again with: task-master login'
+};
+
+/**
+ * Error codes caused by stale sessions that can be recovered from
+ * by clearing the session storage and retrying.
+ *
+ * These errors occur when there's a stale session with an invalid refresh token
+ * and Supabase tries to use it during authentication. The fix is to clear
+ * the stale session and retry the operation.
+ */
+export const RECOVERABLE_STALE_SESSION_ERRORS = [
+ 'refresh_token_not_found',
+ 'refresh_token_already_used'
+] as const;
+
+/**
+ * Check if an error is caused by a stale session and can be recovered
+ * by clearing the session storage and retrying.
+ */
+export function isRecoverableStaleSessionError(error: unknown): boolean {
+ if (!isSupabaseAuthError(error)) return false;
+ return RECOVERABLE_STALE_SESSION_ERRORS.includes(
+ (error.code || '') as (typeof RECOVERABLE_STALE_SESSION_ERRORS)[number]
+ );
+}
+
+/**
+ * Convert a Supabase auth error to a user-friendly AuthenticationError
+ */
+export function toAuthenticationError(
+ error: AuthError,
+ defaultMessage: string
+): AuthenticationError {
+ const code = error.code;
+ const userMessage = code
+ ? AUTH_ERROR_MESSAGES[code] || `${defaultMessage}: ${error.message}`
+ : `${defaultMessage}: ${error.message}`;
+
+ // Map Supabase error codes to our AuthErrorCode
+ let authErrorCode:
+ | 'REFRESH_FAILED'
+ | 'NOT_AUTHENTICATED'
+ | 'INVALID_CREDENTIALS' = 'REFRESH_FAILED';
+ if (
+ code === 'refresh_token_not_found' ||
+ code === 'refresh_token_already_used' ||
+ code === 'invalid_refresh_token' ||
+ code === 'session_expired' ||
+ code === 'user_not_found'
+ ) {
+ authErrorCode = 'NOT_AUTHENTICATED';
+ } else if (code === 'invalid_credentials') {
+ authErrorCode = 'INVALID_CREDENTIALS';
+ }
+
+ return new AuthenticationError(userMessage, authErrorCode, error);
+}
diff --git a/packages/tm-core/src/modules/auth/utils/index.ts b/packages/tm-core/src/modules/auth/utils/index.ts
new file mode 100644
index 00000000..ed367337
--- /dev/null
+++ b/packages/tm-core/src/modules/auth/utils/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Auth utilities exports
+ */
+export {
+ isSupabaseAuthError,
+ AUTH_ERROR_MESSAGES,
+ RECOVERABLE_STALE_SESSION_ERRORS,
+ isRecoverableStaleSessionError,
+ toAuthenticationError
+} from './auth-error-utils.js';
diff --git a/packages/tm-core/src/modules/integration/clients/supabase-client.ts b/packages/tm-core/src/modules/integration/clients/supabase-client.ts
index bbda9075..431b38d5 100644
--- a/packages/tm-core/src/modules/integration/clients/supabase-client.ts
+++ b/packages/tm-core/src/modules/integration/clients/supabase-client.ts
@@ -11,6 +11,11 @@ import {
import { getLogger } from '../../../common/logger/index.js';
import { SupabaseSessionStorage } from '../../auth/services/supabase-session-storage.js';
import { AuthenticationError } from '../../auth/types.js';
+import {
+ isSupabaseAuthError,
+ isRecoverableStaleSessionError,
+ toAuthenticationError
+} from '../../auth/utils/index.js';
export class SupabaseAuthClient {
private static instance: SupabaseAuthClient | null = null;
@@ -98,7 +103,10 @@ export class SupabaseAuthClient {
} = await client.auth.getSession();
if (error) {
- this.logger.warn('Failed to restore session:', error);
+ // MFA-expected errors are normal during auth flows - don't log warnings
+ if (!isRecoverableStaleSessionError(error)) {
+ this.logger.warn('Failed to restore session:', error);
+ }
return null;
}
@@ -108,7 +116,14 @@ export class SupabaseAuthClient {
return session;
} catch (error) {
- this.logger.error('Error initializing session:', error);
+ // MFA-expected errors (refresh_token_not_found, etc.) are normal during auth flows
+ if (isRecoverableStaleSessionError(error)) {
+ this.logger.debug('Session not available (expected during MFA flow)');
+ } else if (isSupabaseAuthError(error)) {
+ this.logger.warn('Session expired or invalid');
+ } else {
+ this.logger.error('Error initializing session:', error);
+ }
return null;
}
}
@@ -213,13 +228,23 @@ export class SupabaseAuthClient {
} = await client.auth.getSession();
if (error) {
- this.logger.warn('Failed to get session:', error);
+ // MFA-expected errors are normal during auth flows - don't log warnings
+ if (!isRecoverableStaleSessionError(error)) {
+ this.logger.warn('Failed to get session:', error);
+ }
return null;
}
return session;
} catch (error) {
- this.logger.error('Error getting session:', error);
+ // MFA-expected errors (refresh_token_not_found, etc.) are normal during auth flows
+ if (isRecoverableStaleSessionError(error)) {
+ this.logger.debug('Session not available (expected during MFA flow)');
+ } else if (isSupabaseAuthError(error)) {
+ this.logger.warn('Session expired or invalid');
+ } else {
+ this.logger.error('Error getting session:', error);
+ }
return null;
}
}
@@ -241,10 +266,8 @@ export class SupabaseAuthClient {
if (error) {
this.logger.error('Failed to refresh session:', error);
- throw new AuthenticationError(
- `Failed to refresh session: ${error.message}`,
- 'REFRESH_FAILED'
- );
+ // Use user-friendly error message for known Supabase auth errors
+ throw toAuthenticationError(error, 'Failed to refresh session');
}
if (session) {
@@ -257,6 +280,11 @@ export class SupabaseAuthClient {
throw error;
}
+ // Handle raw Supabase auth errors that might be thrown
+ if (isSupabaseAuthError(error)) {
+ throw toAuthenticationError(error, 'Session refresh failed');
+ }
+
throw new AuthenticationError(
`Failed to refresh session: ${(error as Error).message}`,
'REFRESH_FAILED'
@@ -341,12 +369,36 @@ export class SupabaseAuthClient {
}
}
+ /**
+ * Handle recoverable stale session errors by clearing storage and retrying.
+ * Returns the result of the retry if applicable, or null if no retry was attempted.
+ */
+ private async handleRecoverableError(
+ error: unknown,
+ isRetry: boolean,
+ retryFn: () => Promise<Session>
+ ): Promise<Session | null> {
+ if (!isRetry && isRecoverableStaleSessionError(error)) {
+ this.logger.debug(
+ 'MFA-expected error during token verification, clearing stale session and retrying'
+ );
+ await this.sessionStorage.clear();
+ return retryFn();
+ }
+ return null;
+ }
+
/**
* Verify a one-time token and create a session
* Used for CLI authentication with pre-generated tokens
+ *
+ * Note: If MFA is enabled and there's a stale session, Supabase might throw
+ * refresh_token_not_found errors. We handle this by clearing the stale session
+ * and retrying once.
*/
- async verifyOneTimeCode(token: string): Promise<Session> {
+ async verifyOneTimeCode(token: string, isRetry = false): Promise<Session> {
const client = this.getClient();
+ const retryFn = () => this.verifyOneTimeCode(token, true);
try {
this.logger.info('Verifying authentication token...');
@@ -359,11 +411,18 @@ export class SupabaseAuthClient {
});
if (error) {
- this.logger.error('Failed to verify token:', error);
- throw new AuthenticationError(
- `Failed to verify token: ${error.message}`,
- 'INVALID_CODE'
+ // If this is an MFA-expected error (like refresh_token_not_found),
+ // it might be due to a stale session interfering. Clear and retry once.
+ const retryResult = await this.handleRecoverableError(
+ error,
+ isRetry,
+ retryFn
);
+ if (retryResult) return retryResult;
+
+ this.logger.error('Failed to verify token:', error);
+ // Use user-friendly error message for known Supabase auth errors
+ throw toAuthenticationError(error, 'Failed to verify token');
}
if (!data?.session) {
@@ -380,6 +439,17 @@ export class SupabaseAuthClient {
throw error;
}
+ // Handle raw Supabase auth errors that might be thrown
+ if (isSupabaseAuthError(error)) {
+ const retryResult = await this.handleRecoverableError(
+ error,
+ isRetry,
+ retryFn
+ );
+ if (retryResult) return retryResult;
+ throw toAuthenticationError(error, 'Token verification failed');
+ }
+
throw new AuthenticationError(
`Token verification failed: ${(error as Error).message}`,
'CODE_AUTH_FAILED'