eyaltoledano/claude-task-master · warning · AuthenticationError

MFA_REQUIRED

MFA_REQUIRED

Error message

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

What it means

Thrown by checkAndThrowIfMFARequired when an OAuth/PKCE login succeeded but the server requires MFA verification, and complete factor information (factorId + factorType) is present. The error carries an MFAChallenge in its `details`/challenge property so the caller can collect a verification code from the user and continue the MFA flow. This is an expected, control-flow error — not a malfunction.

Source

Thrown at packages/tm-core/src/modules/auth/services/oauth-service.ts:472

					mfaCheck
				});
				throw new AuthenticationError(
					'MFA is required but the server returned incomplete factor configuration. Please contact support or try re-enrolling MFA.',
					'MFA_REQUIRED_INCOMPLETE'
				);
			}

			this.logger.info('MFA verification required after OAuth login', {
				factorId: mfaCheck.factorId,
				factorType: mfaCheck.factorType
			});

			const mfaChallenge: MFAChallenge = {
				factorId: mfaCheck.factorId,
				factorType: mfaCheck.factorType
			};

			throw new AuthenticationError(
				'MFA verification required. Please provide your authentication code.',
				'MFA_REQUIRED',
				undefined,
				mfaChallenge
			);
		}
	}
}

View on GitHub (pinned to c0c98d367c)

Solutions

1. Catch the error, read the MFAChallenge from the error details, prompt the user for their TOTP code, and call the MFA verification method with that code
2. Run login in an interactive terminal so the built-in MFA prompt can run (the CLI normally handles this automatically)
3. For CI/automation, create a service account or personal token that bypasses interactive MFA
4. If you have no MFA device, contact an admin or use recovery codes

Example fix

// before: treat all auth errors as fatal
await tmCore.auth.authenticate();
// after: handle the expected MFA step
try {
  await tmCore.auth.authenticate();
} catch (e) {
  if (e instanceof AuthenticationError && e.code === 'MFA_REQUIRED') {
    const challenge = e.details as MFAChallenge; // { factorId, factorType }
    const code = await prompt('Enter your authentication code');
    await tmCore.auth.verifyMfa(challenge.factorId, code);
  }
}

// Nothing to validate beforehand — MFA enforcement is server-side.
// Pre-check available challenge shape before prompting:
function isMfaChallenge(v: unknown): v is { factorId: string; factorType: string } {
  return typeof v === 'object' && v !== null &&
    typeof (v as any).factorId === 'string' &&
    (typeof (v as any).factorType === 'string');
}

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

try {
  await tmCore.auth.authenticate();
} catch (e) {
  if (isMfaRequiredError(e)) {
    const { factorId } = e.details;
    const code = await promptUser('Enter your MFA code');
    await tmCore.auth.verifyMfa(factorId, code);
  } else {
    throw e;
  }
}

When it happens

Trigger: authenticateWithBackendPKCE calls the MFA-check endpoint after OAuth login and the server responds with required=true plus valid factorId and factorType (e.g. user has TOTP enrolled and MFA is enforced).

Common situations: CLI login by a user with MFA enforced on their account; automated scripts/CI running `tm login` interactively-less so the code cannot be entered; users who just enabled MFA and are logging in for the first time.

Understand the failure class

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

Related errors

• MFA_REQUIRED_INCOMPLETE
• MFA_VERIFICATION_FAILED
• FLOW_NOT_FOUND
• OAUTH_FAILED
• AUTH_TIMEOUT

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