{"record":{"id":"16d202a23a9d3fc7","repo":"eyaltoledano/claude-task-master","slug":"mfa-required","errorCode":"MFA_REQUIRED","errorMessage":"'MFA verification required. Please provide your authentication code.'","messagePattern":"'MFA verification required\\. Please provide your authentication code\\.'","errorType":"exception","errorClass":"AuthenticationError","httpStatus":null,"severity":"warning","filePath":"packages/tm-core/src/modules/auth/services/oauth-service.ts","lineNumber":472,"sourceCode":"\t\t\t\t\tmfaCheck\n\t\t\t\t});\n\t\t\t\tthrow new AuthenticationError(\n\t\t\t\t\t'MFA is required but the server returned incomplete factor configuration. Please contact support or try re-enrolling MFA.',\n\t\t\t\t\t'MFA_REQUIRED_INCOMPLETE'\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tthis.logger.info('MFA verification required after OAuth login', {\n\t\t\t\tfactorId: mfaCheck.factorId,\n\t\t\t\tfactorType: mfaCheck.factorType\n\t\t\t});\n\n\t\t\tconst mfaChallenge: MFAChallenge = {\n\t\t\t\tfactorId: mfaCheck.factorId,\n\t\t\t\tfactorType: mfaCheck.factorType\n\t\t\t};\n\n\t\t\tthrow new AuthenticationError(\n\t\t\t\t'MFA verification required. Please provide your authentication code.',\n\t\t\t\t'MFA_REQUIRED',\n\t\t\t\tundefined,\n\t\t\t\tmfaChallenge\n\t\t\t);\n\t\t}\n\t}\n}\n","sourceCodeStart":454,"sourceCodeEnd":481,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/packages/tm-core/src/modules/auth/services/oauth-service.ts#L454-L481","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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","Run login in an interactive terminal so the built-in MFA prompt can run (the CLI normally handles this automatically)","For CI/automation, create a service account or personal token that bypasses interactive MFA","If you have no MFA device, contact an admin or use recovery codes"],"exampleFix":"// before: treat all auth errors as fatal\nawait tmCore.auth.authenticate();\n// after: handle the expected MFA step\ntry {\n  await tmCore.auth.authenticate();\n} catch (e) {\n  if (e instanceof AuthenticationError && e.code === 'MFA_REQUIRED') {\n    const challenge = e.details as MFAChallenge; // { factorId, factorType }\n    const code = await prompt('Enter your authentication code');\n    await tmCore.auth.verifyMfa(challenge.factorId, code);\n  }\n}","handlingStrategy":"try-catch","validationCode":"// Nothing to validate beforehand — MFA enforcement is server-side.\n// Pre-check available challenge shape before prompting:\nfunction isMfaChallenge(v: unknown): v is { factorId: string; factorType: string } {\n  return typeof v === 'object' && v !== null &&\n    typeof (v as any).factorId === 'string' &&\n    (typeof (v as any).factorType === 'string');\n}","typeGuard":"function isMfaRequiredError(e: unknown): e is AuthenticationError & { details: { factorId: string; factorType: string } } {\n  return e instanceof AuthenticationError && e.code === 'MFA_REQUIRED' &&\n    typeof (e.details as any)?.factorId === 'string' &&\n    typeof (e.details as any)?.factorType === 'string';\n}","tryCatchPattern":"try {\n  await tmCore.auth.authenticate();\n} catch (e) {\n  if (isMfaRequiredError(e)) {\n    const { factorId } = e.details;\n    const code = await promptUser('Enter your MFA code');\n    await tmCore.auth.verifyMfa(factorId, code);\n  } else {\n    throw e;\n  }\n}","preventionTips":["Always run login in an interactive terminal so the MFA prompt can display","Wrap authenticate() with explicit MFA_REQUIRED handling in scripts","Use API tokens or service accounts for CI instead of interactive OAuth login","Keep TOTP enrollment active and devices configured before running CLI auth"],"tags":["mfa","oauth","authentication","two-factor"],"backgroundTag":"mfa-challenge-required","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}