{"record":{"id":"cb5c813d8d6ba7d2","repo":"RocketChat/Rocket.Chat","slug":"error-username-reserved-by-bridge","errorCode":"error-username-reserved-by-bridge","errorMessage":"Name is reserved by a federation bridge","messagePattern":"Name is reserved by a federation bridge","errorType":"error_code","errorClass":"MeteorError","httpStatus":null,"severity":"error","filePath":"apps/meteor/ee/server/hooks/federation/index.ts","lineNumber":393,"sourceCode":"\t\treturn;\n\t}\n\n\tif ('name' in userUpdated && userUpdated.name !== oldUserData.name) {\n\t\tvoid FederationMatrix.updateUserName(userUpdated);\n\t}\n});\n\n// Reserve handles that fall within a bridge's exclusive namespace, so a regular user cannot\n// register or rename into a localpart only the bridge is allowed to own. Usernames are checked\n// against the bridge's exclusive `users` namespace; room/team names against its `aliases`/`rooms`\n// namespaces. Inert when federation is disabled (the helper matches against loaded appservice\n// registrations, of which there are none). Every handle assignment path — user creation,\n// SSO/LDAP assignment and renames, plus room renames and team creation — funnels through\n// `checkUsernameAvailability`.\ncheckUsernameAvailabilityCallback.add(\n\t(name, type) => {\n\t\tif (isReservedByExclusiveBridge(type, name)) {\n\t\t\tthrow new MeteorError('error-username-reserved-by-bridge', 'Name is reserved by a federation bridge');\n\t\t}\n\t},\n\tcallbacks.priority.HIGH,\n\t'federation-bridge-namespace',\n);\n","sourceCodeStart":375,"sourceCodeEnd":399,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/ee/server/hooks/federation/index.ts#L375-L399","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Choose a different name outside the bridge's reserved namespace.","If the reservation is wrong, review the appservice registration's exclusive namespace config in the bridge app.","Document reserved prefixes for end users to avoid accidental collisions."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import { isReservedByExclusiveBridge } from '../../lib/federation/bridge';\n\nfunction isNameSafe(type: 'users' | 'rooms', name: string): boolean {\n\treturn !isReservedByExclusiveBridge(type, name);\n}","typeGuard":"function isUsernameReservedByBridgeError(e: unknown): boolean {\n\treturn e instanceof Meteor.Error && (e as Meteor.Error).error === 'error-username-reserved-by-bridge';\n}","tryCatchPattern":"try {\n\tawait checkUsernameAvailabilityCallback.run(name, type);\n} catch (e) {\n\tif (e instanceof Meteor.Error && e.error === 'error-username-reserved-by-bridge') {\n\t\t// pick a name outside the bridge's exclusive namespace\n\t}\n\tthrow e;\n}","preventionTips":["Pre-validate names against `isReservedByExclusiveBridge` before assignment.","Document bridge-reserved namespace prefixes for users and rooms.","Review appservice registration exclusive namespaces when installing bridges."],"tags":["federation","bridge","usernames","validation","ee","meteor-error"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}