The username " " is already being used. Rename or remove…

Error message

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

What it means

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.

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).

Example fix

// before - app manifest
// 'username': 'helper.bot'  (already taken)

// after - app manifest
// 'username': 'helper.bot.tickets'

Defensive patterns

Strategy: validation

Validate before calling

// pre-install check (admin script)
const res = await fetch('/api/v1/users.info?username=helper.bot', { headers });
if (res.status === 200) {
  // username taken: rename it or pick another bot username before installing
}

Prevention

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.

When it happens

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

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

Related errors

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

Appendix: 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 b2c16d5842)