{"record":{"id":"05c7e3e272308c9a","repo":"payloadcms/payload","slug":"validation-required","errorCode":null,"errorMessage":"validation:required","messagePattern":"validation:required","errorType":"validation","errorClass":"ValidationError","httpStatus":400,"severity":"error","filePath":"packages/payload/src/auth/operations/login.ts","lineNumber":125,"sourceCode":"  // /////////////////////////////////////\n  // Login\n  // /////////////////////////////////////\n\n  const { email: unsanitizedEmail, password } = data\n  const loginWithUsername = collectionConfig.auth.loginWithUsername\n\n  const sanitizedEmail =\n    typeof unsanitizedEmail === 'string' ? unsanitizedEmail.toLowerCase().trim() : null\n  const sanitizedUsername =\n    'username' in data && typeof data?.username === 'string'\n      ? data.username.toLowerCase().trim()\n      : null\n\n  const { canLoginWithEmail, canLoginWithUsername } = getLoginOptions(loginWithUsername)\n\n  // cannot login with email, did not provide username\n  if (!canLoginWithEmail && !sanitizedUsername) {\n    throw new ValidationError({\n      collection: collectionConfig.slug,\n      errors: [{ message: req.i18n.t('validation:required'), path: 'username' }],\n    })\n  }\n\n  // cannot login with username, did not provide email\n  if (!canLoginWithUsername && !sanitizedEmail) {\n    throw new ValidationError({\n      collection: collectionConfig.slug,\n      errors: [{ message: req.i18n.t('validation:required'), path: 'email' }],\n    })\n  }\n\n  // can login with either email or username, did not provide either\n  if (!sanitizedUsername && !sanitizedEmail) {\n    throw new ValidationError({\n      collection: collectionConfig.slug,\n      errors: [","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/auth/operations/login.ts#L107-L143","documentation":"A `ValidationError` (400) thrown during login when the collection cannot log in with email (`!canLoginWithEmail`) and no username was supplied. With `loginWithUsername` configured such that email login is disabled, the username is the only accepted identifier; omitting it fails the 'required' validation on the `username` field. The message is the localized `validation:required`.","triggerScenarios":"Collection configured `auth.loginWithUsername: { allowEmailLogin: false }` and the login request sends only an email (or nothing); `data: { email, password }` against a username-only collection.","commonSituations":"Frontend login form built for email but the collection is username-only; mismatched collection config and client expectations; enabling `loginWithUsername` without updating the login UI.","solutions":["Send a `username` in the login data for username-only collections.","Align the collection config (`allowEmailLogin`) with what the login form collects.","Make the client form adapt: collect username when email login is disabled."],"exampleFix":"// before — username-only collection, sending email\nawait payload.login({ collection: 'users', data: { email, password } })\n\n// after — send username\nawait payload.login({ collection: 'users', data: { username, password } })","handlingStrategy":"validation","validationCode":"const loginOpts = getLoginOptions(collection.config.auth.loginWithUsername)\nif (!loginOpts.canLoginWithEmail && !data.username) throw new Error('Username required')","typeGuard":null,"tryCatchPattern":"try {\n  await payload.login({ collection, data })\n} catch (e) {\n  if (e instanceof ValidationError && e.data?.errors?.some(er => er.path === 'username')) {\n    // collect and send a username\n  }\n  throw e\n}","preventionTips":["Match the login form fields to the collection's `loginWithUsername` config.","Send `username` for username-only collections.","Re-check config after enabling/disabling username login."],"tags":["payload","auth","login","validation","username","required"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}