RocketChat/Rocket.Chat · error · MeteorError

error-invalid-scope

error-invalid-scope

Error message

Invalid scope

What it means

Thrown by insertRoleAsync in insertRole.ts:20 when isValidRoleScope(scope) is false. Valid scopes are exactly 'Users' or 'Subscriptions' (see isValidRoleScope.ts). MeteorError code 'error-invalid-scope'.

Source

Thrown at apps/meteor/ee/server/lib/roles/insertRole.ts:20

import type { IRole } from '@rocket.chat/core-typings';
import { Roles } from '@rocket.chat/models';

import { isValidRoleScope } from '../../../../lib/roles/isValidRoleScope';
import { notifyOnRoleChanged } from '../../../../server/lib/notifyListener';

type InsertRoleOptions = {
	broadcastUpdate?: boolean;
};

export const insertRoleAsync = async (roleData: Omit<IRole, '_id' | '_updatedAt'>, options: InsertRoleOptions = {}): Promise<IRole> => {
	const { name, scope, description, mandatory2fa } = roleData;

	if (await Roles.findOneByName(name)) {
		throw new MeteorError('error-duplicate-role-names-not-allowed', 'Role name already exists');
	}

	if (!isValidRoleScope(scope)) {
		throw new MeteorError('error-invalid-scope', 'Invalid scope');
	}

	const role = await Roles.createWithRandomId(name, scope, description, false, mandatory2fa);

	void notifyOnRoleChanged(role);

	if (options.broadcastUpdate) {
		void api.broadcast('user.roleUpdate', {
			type: 'changed',
			_id: role._id,
		});
	}

	return role;
};

View on GitHub (pinned to f9d3ec372b)

Solutions

1. Set scope to 'Users' or 'Subscriptions' explicitly.
2. Validate scope against ['Users','Subscriptions'] before calling insertRoleAsync.
3. Catch MeteorError 'error-invalid-scope' and prompt for a valid scope.

Example fix

// before
await insertRoleAsync({ name, scope: 'Global', description });

// after
const VALID = ['Users', 'Subscriptions'] as const;
const scope = VALID.includes(rawScope) ? rawScope : 'Users';
await insertRoleAsync({ name, scope, description });

import { isValidRoleScope } from '../../../../lib/roles/isValidRoleScope';
// or inline:
const VALID = ['Users', 'Subscriptions'] as const;
if (!VALID.includes(scope)) throw new Error('invalid scope');

const isValidScope = (scope: unknown): scope is 'Users' | 'Subscriptions' =>
  scope === 'Users' || scope === 'Subscriptions';

try { await insertRoleAsync(roleData); }
catch (e) {
  if (e?.code === 'error-invalid-scope') { /* re-prompt */ return; }
  throw e;
}

When it happens

Trigger: Passing a scope that is not in ['Users','Subscriptions'] — e.g. undefined, null, 'Global', 'Rooms', or a custom string.

Common situations: Caller omits scope assuming a default; custom integration assumes a wider scope enum; typo in scope value.

Related errors

• error-invalid-scope
• error-duplicate-role-names-not-allowed
• error-federated-users-in-non-federated-rooms
• error-username-reserved-by-bridge
• error-forwarding-department-target-not-allowed

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