RocketChat/Rocket.Chat · error · Error

Federated user not found locally

Error message

Federated user not found locally

What it means

While creating a federated room, Rocket.Chat first calls FederationMatrix.ensureFederatedUsersExistLocally for each invited member, then re-fetches each by username. If the federation bridge did not actually register the user locally, the subsequent Users.findOneByUsername returns null and this generic Error ('Federated user not found locally') aborts room creation.

Source

Thrown at apps/meteor/server/lib/rooms/createRoom.ts:69

		const { insertedId } = await Subscriptions.createWithRoomAndUser(room, owner, extra);
		await syncRoomRolePriorityForUserAndRoom(owner._id, room._id, ['owner']);

		if (insertedId) {
			await notifyOnSubscriptionChangedById(insertedId, 'inserted');
			await notifyOnRoomChanged(room, 'inserted');
		}

		// Invite federated members to the room SYNCRONOUSLY,
		// since we do not use to invite lots of users at once, this is acceptable.
		const membersToInvite = members.filter((m) => m !== owner.username);

		await FederationMatrix.ensureFederatedUsersExistLocally(membersToInvite);

		for (const memberUsername of membersToInvite) {
			const member = await Users.findOneByUsername(memberUsername);
			if (!member) {
				throw new Error('Federated user not found locally');
			}

			await Room.createUserSubscription({
				ts: new Date(),
				room,
				userToBeAdded: member,
				inviter: owner,
				status: 'INVITED',
			});
		}

		return;
	}

	const subs = [];

	const memberIds = [];

View on GitHub (pinned to b2c16d5842)

Solutions

1. Check federation settings and connectivity to the remote server (federation GUI/Matrix bridge logs), then retry the room creation
2. Inspect the users collection for the expected ghost user (username matching the remote user@domain) to see whether ensureFederatedUsersExistLocally actually persisted it
3. Report/patch ensureFederatedUsersExistLocally if it resolves without creating the user (silent failure in the bridge)

await FederationMatrix.ensureFederatedUsersExistLocally(membersToInvite);
for (const username of membersToInvite) {
  const exists = await Users.findOneByUsername(username, { projections: { _id: 1 } });
  if (!exists) {
    // back off and let the bridge retry provisioning before failing the whole creation
    throw new Error(`Federated user ${username} not provisioned locally yet`);
  }
}

try {
  await createRoom(type, name, owner, members, { federated: true });
} catch (err) {
  if (err instanceof Error && err.message === 'Federated user not found locally') {
    // inspect federation bridge logs, verify remote server reachability, retry with backoff
  }
  throw err;
}

When it happens

Trigger: createRoom with extraData.federated = true and a members list containing remote usernames (user@server.tld): after ensureFederatedUsersExistLocally, Users.findOneByUsername(memberUsername) returns null for at least one member. Happens when the federation bridge silently fails to create the local ghost user or the username casing/format differs.

Common situations: Federation (Matrix bridge) misconfigured or the remote server unreachable while creating a federated channel; version changes in the federation app that alter ghost-user naming; inviting a user whose remote homeserver did not respond to the discovery request.

Related errors

• error-invalid-room
• error-not-authorized-federation
• error-federated-users-in-non-federated-rooms
• error-invalid-configuration
• Federation configuration is invalid,unable to change room ow

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