RocketChat/Rocket.Chat · error · Meteor.Error

error-invalid-roleId

error-invalid-roleId

Error message

error-invalid-roleId

What it means

Thrown by GET roles.getUsersInRole when Roles.findOneById(role, { projection: { _id: 1 } }) returns null. The role value passed does not match any role document. This is a bare Meteor.Error('error-invalid-roleId') with no human message, so clients must key off the error code.

Source

Thrown at apps/meteor/server/api/v1/roles.ts:200

				username: 1,
				emails: 1,
				avatarETag: 1,
				createdAt: 1,
				_updatedAt: 1,
			};

			if (!role) {
				throw new Meteor.Error('error-param-not-provided', 'Query param "role" is required');
			}
			if (roomId && !(await hasPermissionAsync(this.user, 'view-other-user-channels'))) {
				throw new Meteor.Error('error-not-allowed', 'Not allowed');
			}

			const options = { projection: { _id: 1 } };
			const roleData = await Roles.findOneById<Pick<IRole, '_id'>>(role, options);

			if (!roleData) {
				throw new Meteor.Error('error-invalid-roleId');
			}

			const { cursor, totalCount } = await getUsersInRolePaginated(roleData._id, roomId, {
				limit: count,
				sort: { username: 1 },
				skip: offset,
				projection,
			});

			const [users, total] = await Promise.all([cursor.toArray(), totalCount]);

			return API.v1.success({ users, total });
		},
	)
	.post(
		'roles.delete',
		{
			authRequired: true,

View on GitHub (pinned to f9d3ec372b)

Solutions

1. Resolve the role id from GET /api/v1/roles.list before listing users.
2. Confirm the value is the role _id, not the display name (e.g. use 'admin' _id, not 'Admin').
3. Invalidate cached role ids when this error appears and re-fetch the role list.

Example fix

// before
fetch(`/api/v1/roles.getUsersInRole?role=${roleName}`); // name, not id

// after
const { roles } = await fetch('/api/v1/roles.list').then(r => r.json());
const role = roles.find(r => r.name === roleName);
if (!role) throw new Error(`unknown role: ${roleName}`);
fetch(`/api/v1/roles.getUsersInRole?role=${role._id}`);

// Resolve a valid role id before listing users
const { roles } = await fetch('/api/v1/roles.list').then(r => r.json());
const target = roles.find(r => r._id === role || r.name === role)?._id;
if (!target) throw new Error(`unknown role: ${role}`);
fetch(`/api/v1/roles.getUsersInRole?role=${encodeURIComponent(target)}`);

function isRoleId(roles: { _id: string }[], value: string): boolean {
  return roles.some(r => r._id === value);
}

When it happens

Trigger: GET /api/v1/roles.getUsersInRole?role=<unknown> where role is a typo, a deleted role id, or a role name (this lookup is by id only, not by name).

Common situations: Caller passes a role name where an id is expected; role was deleted since the client last fetched the list; id copied from a different workspace.

Related errors

• error-invalid-user
• error-duplicate-role-names-not-allowed
• error-invalid-param
• error-param-not-provided
• error-room-not-found

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