RocketChat/Rocket.Chat · error · MeteorError

error-username-reserved-by-bridge

error-username-reserved-by-bridge

Error message

Name is reserved by a federation bridge

What it means

Thrown by the `checkUsernameAvailability` federation hook (HIGH priority, `federation-bridge-namespace`) when the requested name falls within an appservice bridge's exclusive namespace — `users` namespace for usernames, `aliases`/`rooms` namespaces for room/team names. It is inert when no appservice bridge registrations are loaded. It is a `MeteorError` with code `error-username-reserved-by-bridge`.

Source

Thrown at apps/meteor/ee/server/hooks/federation/index.ts:393

		return;
	}

	if ('name' in userUpdated && userUpdated.name !== oldUserData.name) {
		void FederationMatrix.updateUserName(userUpdated);
	}
});

// Reserve handles that fall within a bridge's exclusive namespace, so a regular user cannot
// register or rename into a localpart only the bridge is allowed to own. Usernames are checked
// against the bridge's exclusive `users` namespace; room/team names against its `aliases`/`rooms`
// namespaces. Inert when federation is disabled (the helper matches against loaded appservice
// registrations, of which there are none). Every handle assignment path — user creation,
// SSO/LDAP assignment and renames, plus room renames and team creation — funnels through
// `checkUsernameAvailability`.
checkUsernameAvailabilityCallback.add(
	(name, type) => {
		if (isReservedByExclusiveBridge(type, name)) {
			throw new MeteorError('error-username-reserved-by-bridge', 'Name is reserved by a federation bridge');
		}
	},
	callbacks.priority.HIGH,
	'federation-bridge-namespace',
);

View on GitHub (pinned to f9d3ec372b)

Solutions

1. Choose a different name outside the bridge's reserved namespace.
2. If the reservation is wrong, review the appservice registration's exclusive namespace config in the bridge app.
3. Document reserved prefixes for end users to avoid accidental collisions.

import { isReservedByExclusiveBridge } from '../../lib/federation/bridge';

function isNameSafe(type: 'users' | 'rooms', name: string): boolean {
	return !isReservedByExclusiveBridge(type, name);
}

function isUsernameReservedByBridgeError(e: unknown): boolean {
	return e instanceof Meteor.Error && (e as Meteor.Error).error === 'error-username-reserved-by-bridge';
}

try {
	await checkUsernameAvailabilityCallback.run(name, type);
} catch (e) {
	if (e instanceof Meteor.Error && e.error === 'error-username-reserved-by-bridge') {
		// pick a name outside the bridge's exclusive namespace
	}
	throw e;
}

When it happens

Trigger: User creation, SSO/LDAP username assignment, user rename, room rename, or team creation proposes a name that `isReservedByExclusiveBridge(type, name)` matches against a loaded appservice bridge's exclusive namespace.

Common situations: A WhatsApp/Slack/Discord bridge is installed with an exclusive namespace prefix (e.g. `@whatsapp_...` or `#slack_...`) and a user attempts to register or rename into that prefix; an admin tries to manually create a room colliding with a bridge's reserved room namespace.

Related errors

• error-federated-users-in-non-federated-rooms
• error-invalid-room
• error-not-authorized-federation
• error-forwarding-department-target-not-allowed
• error-invalid-sla

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