{"record":{"id":"e039dab8bc68296a","repo":"RocketChat/Rocket.Chat","slug":"error-field-unavailable","errorCode":"error-field-unavailable","errorMessage":"${escape(userData.username)} is already in use :(","messagePattern":"(.+?) is already in use :\\(","errorType":"exception","errorClass":"MeteorError","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/lib/users/saveUser/validateUserData.ts","lineNumber":95,"sourceCode":"\n\tif (userData.username && !nameValidation.test(userData.username)) {\n\t\tthrow new MeteorError('error-input-is-not-a-valid-field', `${escape(userData.username)} is not a valid username`, {\n\t\t\tmethod: 'insertOrUpdateUser',\n\t\t\tinput: userData.username,\n\t\t\tfield: 'Username',\n\t\t});\n\t}\n\n\tif (!isUpdateUserData(userData) && !userData.password && !userData.setRandomPassword) {\n\t\tthrow new MeteorError('error-the-field-is-required', 'The field Password is required', {\n\t\t\tmethod: 'insertOrUpdateUser',\n\t\t\tfield: 'Password',\n\t\t});\n\t}\n\n\tif (!isUpdateUserData(userData)) {\n\t\tif (userData.username && !(await checkUsernameAvailability(userData.username))) {\n\t\t\tthrow new MeteorError('error-field-unavailable', `${escape(userData.username)} is already in use :(`, {\n\t\t\t\tmethod: 'insertOrUpdateUser',\n\t\t\t\tfield: userData.username,\n\t\t\t});\n\t\t}\n\n\t\tif (userData.email && !(await checkEmailAvailability(userData.email))) {\n\t\t\tthrow new MeteorError('error-field-unavailable', `${escape(userData.email)} is already in use :(`, {\n\t\t\t\tmethod: 'insertOrUpdateUser',\n\t\t\t\tfield: userData.email,\n\t\t\t});\n\t\t}\n\t}\n});\n","sourceCodeStart":77,"sourceCodeEnd":109,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/users/saveUser/validateUserData.ts#L77-L109","documentation":"Thrown by validateUserData() on CREATE when checkUsernameAvailability() returns false for the submitted username. Availability is not just uniqueness: the shared helper (server/lib/users/checkUsernameAvailability.ts) also runs it against reserved words and external-directory collisions via the checkUsernameAvailabilityCallback, so some 'available-looking' names are still blocked. Code is error-field-unavailable and the message echoes the escaped username.","triggerScenarios":"users.create with a username already owned by another user, matched case-insensitively; a username on the reserved list (e.g. 'admin' variants) even though no user holds it; collisions with an LDAP/external user cache entry.","commonSituations":"Bulk import colliding with existing accounts; retrying a create after a partial success; test scripts reusing a fixed username; usernames differing only in case or trailing punctuation being normalized to an existing one.","solutions":["Check first with the dedicated endpoint: GET /api/v1/users.checkUsernameAvailability?username=... (api/v1/users.ts:1228) and only proceed when it returns true.","On 409/unavailable, fetch a suggestion via GET /api/v1/users.getUsernameSuggestion (api/v1/users.ts:1177) and either use it or surface it to the user.","For imports, de-duplicate against GET /api/v1/users.list before submitting, and suffix colliding names deterministically."],"exampleFix":"// before\nawait POST '/api/v1/users.create', { username: 'alice', email: 'a1@b.c', password: 'pw' }); // throws 'already in use'\n\n// after\nconst ok = await GET `/api/v1/users.checkUsernameAvailability?username=alice`;\nconst username = ok.available ? 'alice' : (await GET '/api/v1/users.getUsernameSuggestion?username=alice').result;\nawait POST '/api/v1/users.create', { username, email: 'a1@b.c', password: 'pw' });","handlingStrategy":"validation","validationCode":"const { result: available } = await GET `/api/v1/users.checkUsernameAvailability?username=${encodeURIComponent(u)}`;\nif (!available) {\n  const { result: suggestion } = await GET `/api/v1/users.getUsernameSuggestion?username=${encodeURIComponent(u)}`;\n  payload.username = suggestion;\n}","typeGuard":"null","tryCatchPattern":"catch (e) {\n  if (e.error === 'error-field-unavailable' && e.details?.field === u) {\n    // fetch a suggestion and resubmit once\n  }\n}","preventionTips":["Check availability on blur, not just submit.","Suffix deterministic seeds (alice, alice2, alice3) in imports.","Treat reserved-word blocks as permanent; do not retry unchanged."],"tags":["users","username","availability","conflict","save-user"],"backgroundTag":"username-already-taken","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}