What causes "Query param "role" is required" in RocketChat/Rocket.Chat?

Always include a non-empty role query param when calling roles.getUsersInRole.

RocketChat/Rocket.Chat · error · Meteor.Error

error-param-not-provided

error-param-not-provided

Error message

Query param "role" is required

What it means

Thrown by GET roles.getUsersInRole when the role query param is missing or falsy. The route requires the 'access-permissions' permission and uses the isRolesGetUsersInRoleProps query schema, but the action additionally enforces that role is non-empty here. Returns a structured Meteor.Error('error-param-not-provided', ...).

Source

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

				401: validateUnauthorizedErrorResponse,
				403: validateForbiddenErrorResponse,
			},
		},
		async function action() {
			const { roomId, role } = this.queryParams;
			const { offset, count = 50 } = await getPaginationItems(this.queryParams);

			const projection = {
				name: 1,
				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,
			});

View on GitHub (pinned to f9d3ec372b)

Solutions

Always include a non-empty role query param when calling roles.getUsersInRole.
Use GET /api/v1/roles.list to discover valid role ids/names first.
Disable the submit action in the UI until a role is selected.

Example fix

// before
fetch(`/api/v1/roles.getUsersInRole${role ? `?role=${role}` : ''}`);

// after
if (!role) throw new Error('role is required');
fetch(`/api/v1/roles.getUsersInRole?role=${encodeURIComponent(role)}`);

Defensive patterns

Strategy: validation

Validate before calling

if (!role || role.trim() === '') throw new Error('role query param is required');
fetch(`/api/v1/roles.getUsersInRole?role=${encodeURIComponent(role)}`);

Type guard

function hasRoleParam(qs: Record<string, unknown>): qs is { role: string } {
  return typeof qs.role === 'string' && qs.role.length > 0;
}

Prevention

Disable submit until a role is chosen.
Fetch the role list first so callers select a valid id.

When it happens

Trigger: GET /api/v1/roles.getUsersInRole with no role param, role=, or role='' (empty string).

Common situations: Client builds the query conditionally and omits role when a dropdown is empty; URL templating bug strips the param; copy-paste from a different endpoint.

Related errors

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