What causes "Cannot add federated users to non-federated rooms" in RocketChat/Rocket.Chat?

Enable federation on the target room before inviting federated users, or convert it to a federated room.

RocketChat/Rocket.Chat · error · MeteorError

error-federated-users-in-non-federated-rooms

error-federated-users-in-non-federated-rooms

Error message

Cannot add federated users to non-federated rooms

What it means

Thrown by the `beforeAddUsersToRoom` federation hook when federation should NOT be performed for the room (`FederationActions.shouldPerformFederationAction(room)` is false), the inviter exists, AND one or more of the requested usernames validate as federated usernames (`validateFederatedUsername`). It prevents inviting external/federated users into a room that is not itself federated.

Source

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

		// deletion came from federation — don't echo
		if (isUserNativeFederated(user)) {
			return;
		}

		if (FederationActions.shouldPerformFederationAction(room)) {
			await FederationMatrix.deleteMessage(room.federation.mrid, message);
		}
	},
	callbacks.priority.MEDIUM,
	'native-federation-after-delete-message',
);

beforeAddUsersToRoom.add(async ({ usernames, inviter }, room) => {
	if (!FederationActions.shouldPerformFederationAction(room) && inviter) {
		// check if trying to invite a federated user to a non-federated room
		const federatedUsernames = usernames.filter((u) => validateFederatedUsername(u));
		if (federatedUsernames.length > 0) {
			throw new MeteorError('error-federated-users-in-non-federated-rooms', 'Cannot add federated users to non-federated rooms');
		}
		return;
	}

	// we create local users before adding them to the room
	await FederationMatrix.ensureFederatedUsersExistLocally(usernames);
});

beforeAddUserToRoom.add(
	async ({ user, inviter }, room) => {
		if (!user.username || !inviter) {
			return;
		}

		if (!FederationActions.shouldPerformFederationAction(room)) {
			return;
		}

View on GitHub (pinned to f9d3ec372b)

Solutions

Enable federation on the target room before inviting federated users, or convert it to a federated room.
Remove federated usernames from the invite list when targeting a non-federated room.
Surface a clear UI message explaining federated users can only join federated rooms.

Defensive patterns

Strategy: validation

Validate before calling

import { validateFederatedUsername } from '@rocket.chat/core-typings';

function inviteContainsFederatedUsers(usernames: string[]): boolean {
	return usernames.filter(validateFederatedUsername).length > 0;
}

// before adding users to a non-federated room:
if (!isRoomFederated(room) && inviteContainsFederatedUsers(usernames)) {
	throw new Error('Cannot invite federated users to a non-federated room');
}

Type guard

function isFederatedUsersInNonFederatedRoomError(e: unknown): boolean {
	return e instanceof Meteor.Error && (e as Meteor.Error).error === 'error-federated-users-in-non-federated-rooms';
}

Try / catch

try {
	await beforeAddUsersToRoom.run({ usernames, inviter }, room);
} catch (e) {
	if (e instanceof Meteor.Error && e.error === 'error-federated-users-in-non-federated-rooms') {
		// remove federated usernames or federate the room first
	}
	throw e;
}

Prevention

Filter federated usernames out of invite lists for non-federated rooms.
Make the room federated before inviting external users.
Show clear UI guidance that federated users require federated rooms.

When it happens

Trigger: Calling add-users-to-room with a username like `@user:remote.server` (passes `validateFederatedUsername`) on a room where `shouldPerformFederationAction(room)` returns false and an `inviter` is present.

Common situations: User tries to @-mention/invite a federated handle into a regular non-federated private channel; UI permits selecting a federated contact for a local-only room; federation disabled on the room after it was created.

Related errors

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