What causes "User not found" in RocketChat/Rocket.Chat?

Verify the username first (GET /api/v1/users.info?username=...) and correct it.

RocketChat/Rocket.Chat · error · Meteor.Error

error-user-not-found

error-user-not-found

Error message

User not found

What it means

addUserToRole() resolves the target by username case-insensitively with Users.findOneByUsernameIgnoringCase; no matching user document throws error-user-not-found. Only _id is projected — the user must already exist, there is no auto-invite behavior on this path.

Source

Thrown at apps/meteor/server/meteor-methods/auth/addUserToRole.ts:46

			method: 'authorization:addUserToRole',
		});
	}

	if (role._id === 'admin' && !(await hasPermissionAsync(userId, 'assign-admin-role'))) {
		throw new Meteor.Error('error-action-not-allowed', 'Assigning admin is not allowed', {
			method: 'authorization:addUserToRole',
			action: 'Assign_admin',
		});
	}

	const user = await Users.findOneByUsernameIgnoringCase(username, {
		projection: {
			_id: 1,
		},
	});

	if (!user?._id) {
		throw new Meteor.Error('error-user-not-found', 'User not found', {
			method: 'authorization:addUserToRole',
		});
	}

	// verify if user can be added to given scope
	if (scope && !(await Roles.canAddUserToRole(user._id, role._id, scope))) {
		throw new Meteor.Error('error-invalid-user', 'User is not part of given room', {
			method: 'authorization:addUserToRole',
		});
	}

	const add = await addUserRolesAsync(user._id, [role._id], scope);

	if (settings.get('UI_DisplayRoles')) {
		void api.broadcast('user.roleUpdate', {
			type: 'added',
			_id: role._id,
			u: {

View on GitHub (pinned to b2c16d5842)

Solutions

Verify the username first (GET /api/v1/users.info?username=...) and correct it.
Refresh the user picker — the user may have been deleted or renamed.
If invoked right after signup, retry once the user record is confirmed to exist.

Example fix

// before: typo'd username -> error-user-not-found
Meteor.call('authorization:addUserToRole', roleId, 'jonh.doe');

// after: verify then call with the exact username
const info = await getUserByUsername('john.doe'); // GET /api/v1/users.info?username=john.doe
if (!info) throw new Error('no such user');
Meteor.call('authorization:addUserToRole', roleId, info.user.username);

Defensive patterns

Strategy: validation

Validate before calling

// Verify the target user exists before assigning a role
const res = await fetch(`/api/v1/users.info?username=${encodeURIComponent(username)}`, {
  headers: { 'X-Auth-Token': token, 'X-User-Id': uid },
});
if (!res.ok) throw new Error(`no user named ${username}`);

Try / catch

try {
  await Meteor.callAsync('authorization:addUserToRole', roleId, username, scope);
} catch (err: any) {
  if (err?.error === 'error-user-not-found' && err?.details?.method === 'authorization:addUserToRole') {
    // stale picker or typo: re-resolve the username, then retry once
    const fresh = await resolveUsername(username);
    return fresh ? Meteor.callAsync('authorization:addUserToRole', roleId, fresh, scope) : undefined;
  }
  throw err;
}

Prevention

Resolve usernames through users.info before role assignment.
Refresh user pickers after user deletions/renames.
In scaled deployments, confirm the user record exists before acting immediately after signup.

When it happens

Trigger: authorization:addUserToRole / roles.addUserToRole with a username that does not exist, has a typo, or refers to a deleted user; usernames taken from a stale admin picker; calling immediately after signup before the record is visible (replication lag in scaled setups).

Common situations: Typo'd usernames; deleted or deactivated users still listed in UI; federated/app users stored under different usernames than expected.

Related errors

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