{"record":{"id":"282d5805b9aa1042","repo":"RocketChat/Rocket.Chat","slug":"the-username-user-username-is-already-being-u","errorCode":null,"errorMessage":"The username \"${user.username}\" is already being used. Rename or remove the user using it to install this App","messagePattern":"The username \"(.+?)\" is already being used\\. Rename or remove the user using it to install this App","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"apps/meteor/app/apps/server/bridges/users.ts","lineNumber":93,"sourceCode":"\t\t// #TODO: #AppsEngineTypes - Remove explicit types and typecasts once the apps-engine definition/implementation mismatch is fixed.\n\t\tconst user = this.orch\n\t\t\t.getConverters()\n\t\t\t?.get('users')\n\t\t\t.convertToRocketChat(userDescriptor as IUser);\n\n\t\tif (!user._id) {\n\t\t\tuser._id = Random.id();\n\t\t}\n\n\t\tif (!user.createdAt) {\n\t\t\tuser.createdAt = new Date();\n\t\t}\n\n\t\tswitch (user.type) {\n\t\t\tcase 'bot':\n\t\t\tcase 'app':\n\t\t\t\tif (!(await checkUsernameAvailability(user.username as string))) {\n\t\t\t\t\tthrow new Error(`The username \"${user.username}\" is already being used. Rename or remove the user using it to install this App`);\n\t\t\t\t}\n\n\t\t\t\tawait Users.insertOne(user);\n\n\t\t\t\tif (options?.avatarUrl) {\n\t\t\t\t\tawait setUserAvatar(user, options.avatarUrl, '', 'local');\n\t\t\t\t}\n\n\t\t\t\tbreak;\n\n\t\t\tdefault:\n\t\t\t\tthrow new Error('Creating normal users is currently not supported');\n\t\t}\n\n\t\tvoid notifyOnUserChangeById({ clientAction: 'inserted', id: user._id });\n\n\t\treturn user._id;\n\t}","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/app/apps/server/bridges/users.ts#L75-L111","documentation":"When an app creates its app/bot user (normally at install time), the users bridge first checks that the requested username is free. checkUsernameAvailability returning false aborts creation with this error, because two Rocket.Chat users cannot share a username — the existing owner of the name blocks the install.","triggerScenarios":"Installing an app whose manifest bot username collides with an existing user; reinstalling an app whose previous bot user was not fully removed; installing a second copy/fork of an app that declares the same bot username.","commonSituations":"Reinstall after a failed uninstall left the bot user behind; dev workspace already containing the bot from a forked app; bot username matching a real person's username.","solutions":["Rename the existing user, or change the app's bot username in its manifest, then (re)install.","Remove the leftover bot user from the previous installation (Administration > Users) before reinstalling.","To run two copies of an app, give each a distinct bot username (e.g. suffix per environment)."],"exampleFix":"// before - app manifest\n// 'username': 'helper.bot'  (already taken)\n\n// after - app manifest\n// 'username': 'helper.bot.tickets'","handlingStrategy":"validation","validationCode":"// pre-install check (admin script)\nconst res = await fetch('/api/v1/users.info?username=helper.bot', { headers });\nif (res.status === 200) {\n  // username taken: rename it or pick another bot username before installing\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Namespace bot usernames per app and environment.","After uninstalling, verify the bot user is actually gone before reinstalling.","Check Admin > Users for the planned bot username before first install."],"tags":["apps-engine","app-install","username","bot-user"],"backgroundTag":"username-already-taken","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","contentChangedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}