{"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":"Error","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/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/app/apps/server/bridges/users.ts#L75-L111","documentation":"Thrown by the users bridge create method when installing a bot/app-typed user whose username is already taken. Before inserting the app user, the bridge calls checkUsernameAvailability; failure means another user (human, bot, or app) already owns that username, which would collide in Rocket.Chat's unique username namespace.","triggerScenarios":"App installation or re-installation tries to create its bot/app user with a username that already exists — e.g. reinstalling an app without cleanup, two apps claiming the same bot username, or a human user took the bot's intended username.","commonSituations":"Reinstalling an app whose previous user record was not fully removed; username collision between apps; admin manually created a user with the bot's reserved username; app renamed but the old bot user lingers.","solutions":["Rename or remove the existing user that owns the colliding username before installing the app.","If reinstalling, ensure the prior app's bot user is purged first.","Choose a unique, app-prefixed username for the bot user to avoid collisions."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await users.create(botUser);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('already being used')) {\n    // rename or remove the conflicting user, then retry\n  } else {\n    throw err;\n  }\n}","preventionTips":["Use a unique, app-prefixed bot username to avoid collisions.","Ensure prior app bot users are removed before reinstalling.","CheckUsernameAvailability before attempting create."],"tags":["apps-engine","users","bot","username","conflict"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}