eyaltoledano/claude-task-master · warning · AuthenticationError

MFA_REQUIRED

MFA_REQUIRED

Error message

'MFA verification required. Please provide your authentication code.'

What it means

AuthenticationError with code MFA_REQUIRED thrown by authenticateWithCode when checkMFARequired() reports the user has MFA enabled (required=true with factorId and factorType). This is an expected control-flow signal, not a malfunction: the one-time code authenticated the user, but a second factor must be verified via verifyMFA(factorId, code) before credentials are issued.

Source

Thrown at packages/tm-core/src/modules/auth/services/session-manager.ts:255

				);
			}

			// Get user information
			const user = await this.supabaseClient.getUser();

			if (!user) {
				throw new AuthenticationError(
					'Failed to get user information',
					'INVALID_RESPONSE'
				);
			}

			// Check if MFA is required for this user
			const mfaCheck = await this.supabaseClient.checkMFARequired();

			if (mfaCheck.required && mfaCheck.factorId && mfaCheck.factorType) {
				// MFA is required - throw an error with the MFA challenge information
				throw new AuthenticationError(
					'MFA verification required. Please provide your authentication code.',
					'MFA_REQUIRED',
					undefined,
					{
						factorId: mfaCheck.factorId,
						factorType: mfaCheck.factorType
					}
				);
			}

			// Store user context
			this.contextStore.saveContext({
				userId: user.id,
				email: user.email
			});

			// Build credentials response
			const context = this.contextStore.getUserContext();

View on GitHub (pinned to c0c98d367c)

Solutions

1. Catch this error, prompt the user for their MFA code, and call sessionManager.verifyMFA(err.details.factorId, code)
2. Factor the factorType (e.g. totp) into the prompt shown to the user
3. For non-interactive automation, use a service account without MFA or an alternate auth path
4. Document in your tooling that MFA-enabled accounts require the two-step token + MFA flow

Example fix

// before: assuming single-step auth
await sessionManager.authenticateWithCode(token);
// after: handle MFA step
try {
  await sessionManager.authenticateWithCode(token);
} catch (e) {
  if (e instanceof AuthenticationError && e.code === 'MFA_REQUIRED') {
    const code = await prompt('Enter MFA code:');
    await sessionManager.verifyMFA(e.details.factorId, code);
  }
}

// no local pre-check possible: MFA enrollment is server-side.
// Design callers to expect MFA_REQUIRED whenever user accounts may have factors.

function isMfaRequired(e: unknown): e is AuthenticationError & { details: { factorId: string; factorType: string } } {
  return e instanceof AuthenticationError && e.code === 'MFA_REQUIRED' &&
    !!e.details?.factorId;
}

try {
  await sessionManager.authenticateWithCode(token);
} catch (e) {
  if (isMfaRequired(e)) {
    const code = await prompt(`Enter ${e.details.factorType} code:`);
    await sessionManager.verifyMFA(e.details.factorId, code);
  } else throw e;
}

When it happens

Trigger: Calling authenticateWithCode(token) for any user who has enrolled an MFA factor in Supabase; factorId/factorType are attached to the error so callers can immediately prompt for the verification code and call verifyMFA.

Common situations: Users with TOTP or other MFA factors enrolled running headless/SSH CLI login; scripts written before MFA was enabled on the account suddenly hitting this; automation that never handles the MFA step.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• MFA_VERIFICATION_FAILED
• MFA_REQUIRED
• NO_TOKEN
• MFA_VERIFICATION_FAILED
• MFA_VERIFICATION_FAILED

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