n8n-io/n8n · error · AuthError

MFA not used during authentication

Error message

MFA not used during authentication

What it means

MFA is enforced for the deployment, the user has MFA enabled, but the request's auth cookie was issued without completing an MFA step (usedMfa === false). The middleware refuses to grant full access and throws AuthError, which is caught and results in cookie clearing + 401. The user must re-authenticate including the MFA step. This is distinct from the mfaEnrollmentRequired branch where the user has not yet set up MFA.

Source

Thrown at packages/cli/src/auth/auth.service.ts:142

		allowSkipPreviewAuth,
		allowUnauthenticated,
	}: CreateAuthMiddlewareOptions) {
		return async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
			const token = req.cookies[AUTH_COOKIE_NAME];

			if (token) {
				try {
					const isInvalid = await this.invalidAuthTokenRepository.existsBy({ token });
					if (isInvalid) throw new AuthError('Unauthorized');

					const [user, { usedMfa }] = await this.resolveJwt(token, req, res);
					const mfaEnforced = await this.mfaService.isMFAEnforced();

					if (mfaEnforced && !usedMfa && !allowSkipMFA) {
						// If MFA is enforced, we need to check if the user has MFA enabled and used it during authentication
						if (user.mfaEnabled) {
							// If the user has MFA enforced, but did not use it during authentication, we need to throw an error
							throw new AuthError('MFA not used during authentication');
						} else {
							// User doesn't have MFA enabled, but MFA is enforced
							// They need to set up MFA before accessing most endpoints
							if (allowUnauthenticated) {
								// Don't set req.user to avoid giving full access to semi-authenticated users
								// Instead, set a flag in authInfo to indicate MFA enrollment is required
								// This allows endpoints to handle this state appropriately (e.g., return public settings)
								req.authInfo = {
									usedMfa,
									mfaEnrollmentRequired: true,
								};
								return next();
							}

							// In this case we don't want to clear the cookie, to allow for MFA setup
							res.status(401).json({ status: 'error', message: 'Unauthorized', mfaRequired: true });
							return;
						}

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Have the user log out and back in, completing the MFA challenge so the new cookie carries usedMfa = true.
2. If using a custom login client, ensure the MFA verification step runs before accepting the session cookie.
3. Verify the JWT includes the MFA-used claim after a successful MFA login; if not, check the login service.

Example fix

// login flow (client)
// before: accept session after password only
const { token } = await login(user, pass);
setCookie(token); // cookie lacks usedMfa -> 1279 on next request

// after: complete MFA then accept
const { mfaTicket } = await login(user, pass);
const { token } = await verifyMfa(mfaTicket, code);
setCookie(token);

// Client: ensure MFA step completes before persisting the session cookie
const { mfaTicket } = await login(user, pass);
if (mfaTicket) {
  const { token } = await verifyMfa(mfaTicket, code);
  setCookie(token);
} else {
  setCookie(passwordToken); // only when MFA is not enforced
}

import { AuthError } from 'n8n-workflow';
function isMfaRequiredError(e: unknown): boolean {
  return e instanceof AuthError && /MFA not used/i.test(e.message);
}

// Express middleware
try {
  await next();
} catch (err) {
  if (err instanceof AuthError && /MFA not used/i.test(err.message)) {
    res.clearCookie(AUTH_COOKIE_NAME);
    return res.status(401).json({ status: 'error', message: 'MFA required', mfaRequired: true });
  }
  throw err;
}

When it happens

Trigger: A user logs in with username/password but does not complete the MFA challenge, then attempts to access a protected endpoint; an admin enables MFA enforcement after the user obtained a non-MFA session; the MFA challenge was skipped or failed silently and the session cookie lacks the usedMfa flag.

Common situations: Admin turns on MFA enforcement while users have active non-MFA sessions; a login flow bug that issues the auth cookie before MFA completion; client that bypasses the MFA step; clock/token state that drops the usedMfa claim.

Understand the failure class

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

Related errors

• Unauthorized
• If MFA enabled, mfaCode is required.
• Invalid MFA token.
• LangSmithTelemetry creates its own tracer — do not use .otlp
• No suspended run found for runId: ${this.runId}

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/0764048087a2fa67. Report an issue: GitHub.