RocketChat/Rocket.Chat · error · Error

The username "${user.username}" is already being used. Renam

Error message

The username "${user.username}" is already being used. Rename or remove the user using it to install this App

What it means

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.

Source

Thrown at apps/meteor/app/apps/server/bridges/users.ts:93

		// #TODO: #AppsEngineTypes - Remove explicit types and typecasts once the apps-engine definition/implementation mismatch is fixed.
		const user = this.orch
			.getConverters()
			?.get('users')
			.convertToRocketChat(userDescriptor as IUser);

		if (!user._id) {
			user._id = Random.id();
		}

		if (!user.createdAt) {
			user.createdAt = new Date();
		}

		switch (user.type) {
			case 'bot':
			case 'app':
				if (!(await checkUsernameAvailability(user.username as string))) {
					throw new Error(`The username "${user.username}" is already being used. Rename or remove the user using it to install this App`);
				}

				await Users.insertOne(user);

				if (options?.avatarUrl) {
					await setUserAvatar(user, options.avatarUrl, '', 'local');
				}

				break;

			default:
				throw new Error('Creating normal users is currently not supported');
		}

		void notifyOnUserChangeById({ clientAction: 'inserted', id: user._id });

		return user._id;
	}

View on GitHub (pinned to f9d3ec372b)

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.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await users.create(botUser);
} catch (err) {
  if (err instanceof Error && err.message.includes('already being used')) {
    // rename or remove the conflicting user, then retry
  } else {
    throw err;
  }
}

Prevention

Use a unique, app-prefixed bot username to avoid collisions.
Ensure prior app bot users are removed before reinstalling.
CheckUsernameAvailability before attempting create.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@f9d3ec372b (2026-08-12). Data as JSON: /api/errors/282d5805b9aa1042. Report an issue: GitHub.