{"record":{"id":"c9e6b2a409d1bf8b","repo":"RocketChat/Rocket.Chat","slug":"username-invalid","errorCode":"username-invalid","errorMessage":"${_.escape(username)} is not a valid username, use only letters, numbers, dots, hyphens and underscores","messagePattern":"(.+?) is not a valid username, use only letters, numbers, dots, hyphens and underscores","errorType":"exception","errorClass":"Meteor.Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/lib/users/setUsername.ts","lineNumber":57,"sourceCode":"\t\tthrow new Meteor.Error('error-invalid-user', 'Invalid user', { method: 'setUsername' });\n\t}\n\n\tif (isUserNativeFederated(user) || (await isUserInFederatedRooms(userId))) {\n\t\tthrow new Meteor.Error('error-not-allowed', 'Cannot change username for federated users or users in federated rooms', {\n\t\t\tmethod: 'setUsername',\n\t\t});\n\t}\n\n\tif (user.username && !settings.get('Accounts_AllowUsernameChange')) {\n\t\tthrow new Meteor.Error('error-not-allowed', 'Not allowed');\n\t}\n\n\tif (user.username === username || (user.username && user.username.toLowerCase() === username.toLowerCase())) {\n\t\treturn;\n\t}\n\n\tif (!validateUsername(username)) {\n\t\tthrow new Meteor.Error(\n\t\t\t'username-invalid',\n\t\t\t`${_.escape(username)} is not a valid username, use only letters, numbers, dots, hyphens and underscores`,\n\t\t);\n\t}\n\n\tif (!(await checkUsernameAvailability(username))) {\n\t\tthrow new Meteor.Error('error-field-unavailable', `<strong>${_.escape(username)}</strong> is already in use :(`, {\n\t\t\tmethod: 'setUsername',\n\t\t\tfield: username,\n\t\t});\n\t}\n\n\tif (!(await saveUserIdentity({ _id: user._id, username }))) {\n\t\tthrow new Meteor.Error('error-could-not-change-username', 'Could not change username', {\n\t\t\tmethod: 'setUsername',\n\t\t});\n\t}\n","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/users/setUsername.ts#L39-L75","documentation":"validateUsername() rejected the proposed name: it does not match the regex built from the UTF8_User_Names_Validation setting (default ^[0-9a-zA-Z-_.]+$ when the setting is empty or not a valid regex) — hence 'use only letters, numbers, dots, hyphens and underscores'. The check runs after the same-name early return, so it only fires for genuinely new names.","triggerScenarios":"Submitting a username containing spaces, accented/non-ASCII letters, emoji, or other symbols when UTF8_User_Names_Validation has not been loosened; or a name that fails a custom regex the admin installed in that setting.","commonSituations":"Auto-deriving usernames from email local parts or display names without sanitizing; user bases with diacritics; tightening the regex after forms were already rendered. If the setting holds an invalid regex it silently falls back to the default pattern.","solutions":["Sanitize before submit: trim and strip characters outside [0-9a-zA-Z-_.] (or slugify with limax)","If the workspace intentionally allows unicode usernames, set UTF8_User_Names_Validation to a matching regex fragment","Mirror the active regex in client-side form validation so users get feedback before the round-trip"],"exampleFix":"// before\nawait setUsernameWithValidation(userId, 'josé ça-va'); // username-invalid\n\n// after\nconst clean = username.trim().replace(/[^0-9a-zA-Z-_.]/g, '');\nif (!/^[0-9a-zA-Z-_.]+$/.test(clean)) throw new Error('pick another name');\nawait setUsernameWithValidation(userId, clean);","handlingStrategy":"validation","validationCode":"// mirror the server rule (UTF8_User_Names_Validation or the default)\nconst USERNAME_RE = /^[0-9a-zA-Z-_.]+$/;\nconst clean = username.trim();\nif (!USERNAME_RE.test(clean)) {\n  // block submit and show the allowed-charset hint\n}","typeGuard":"const isValidUsername = (v: unknown): v is string => typeof v === 'string' && /^[0-9a-zA-Z-_.]+$/.test(v.trim());","tryCatchPattern":"try {\n  await setUsernameWithValidation(userId, username);\n} catch (error) {\n  if (error instanceof Meteor.Error && error.error === 'username-invalid') {\n    // show the allowed-charset hint next to the input\n  } else {\n    throw error;\n  }\n}","preventionTips":["Never build usernames from raw email local parts or display names — sanitize first","Keep the client-side regex in sync with UTF8_User_Names_Validation","Trim input before validating; edge whitespace is the most common silent cause"],"tags":["username","validation","regex","settings","meteor"],"backgroundTag":"invalid-username-format","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}