What causes "Failed to convert some role names to ids" in RocketChat/Rocket.Chat?

Compare the warned role list against Administration > Roles and correct the names/ids in the SAML provider settings

Failed to convert some role names to ids

Error message

Failed to convert some role names to ids

What it means

During SAML login, configured role names/ids are resolved to internal role ids via Roles.findInIdsOrNames after trimming. If some configured roles match nothing in the Roles collection, this warning lists them; if none resolve at all, the function throws ('We should have at least one existing role...') and login fails.

Source

Thrown at apps/meteor/server/lib/saml/lib/SAML.ts:42

const showErrorMessage = function (res: ServerResponse, err: string): void {
	res.writeHead(200, {
		'Content-Type': 'text/html',
	});
	const content = `<html><body><h2>Sorry, an annoying error occured</h2><div>${escapeHTML(err)}</div></body></html>`;
	res.end(content, 'utf-8');
};

const convertRoleNamesToIds = async (roleNamesOrIds: string[]): Promise<IRole['_id'][]> => {
	const normalizedRoleNamesOrIds = roleNamesOrIds.map((role) => role.trim()).filter((role) => role.length > 0);
	if (!normalizedRoleNamesOrIds.length) {
		throw new Error(`No valid role names or ids provided for conversion: ${roleNamesOrIds.join(', ')}`);
	}

	const roles = (await Roles.findInIdsOrNames(normalizedRoleNamesOrIds).toArray()).map((role) => role._id);

	if (roles.length !== normalizedRoleNamesOrIds.length) {
		SystemLogger.warn({
			msg: 'Failed to convert some role names to ids',
			roles: normalizedRoleNamesOrIds,
		});
	}

	if (!roles.length) {
		throw new Error(`We should have at least one existing role to create the user: ${normalizedRoleNamesOrIds.join(', ')}`);
	}

	return roles;
};

export class SAML {
	public static async processRequest(
		req: IIncomingMessage,
		res: ServerResponse,
		service: IServiceProviderOptions,
		samlObject: ISAMLAction,

View on GitHub (pinned to 2a7de45707)

Solutions

Compare the warned role list against Administration > Roles and correct the names/ids in the SAML provider settings
Create the missing roles or map the IdP attribute to existing ones
Clean up the mapping list — trailing commas or stray separators produce empty/invalid entries
If login fails with 'We should have at least one existing role', ensure at least one mapped role exists as a valid fallback

Example fix

// before (SAML role mapping)
roles: ['admin', 'suport-team'] // 'suport-team' does not exist

// after
roles: ['admin', 'support-team'] // matches role in Administration > Roles

Defensive patterns

Strategy: validation

Validate before calling

const normalized = roleNamesOrIds.map((r) => r.trim()).filter(Boolean);
const existing = await Roles.findInIdsOrNames(normalized).toArray();
const existingIds = new Set(existing.map((r) => r._id));
const existingNames = new Set(existing.map((r) => r.name?.toLowerCase()).filter(Boolean));
const missing = normalized.filter((r) => !existingIds.has(r) && !existingNames.has(r.toLowerCase()));
if (missing.length) {
  throw new Error(`SAML role mapping references unknown roles: ${missing.join(', ')}`);
}

Prevention

Validate SAML role mappings against Administration > Roles whenever roles change
Prefer stable role ids over display names in mappings
Keep at least one guaranteed-existing fallback role so login never hard-fails

When it happens

Trigger: SAML settings (role attribute mapping, default roles on user creation) reference roles that do not exist in Administration > Roles — deleted, renamed, misspelled, or referenced by name where only the id differs.

Common situations: An admin deletes/renames a role after SAML mapping was configured; IdP sends role values that were never created in Rocket.Chat; environment drift between staging (role exists) and production (role missing).

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@2a7de45707 (2026-08-18). Data as JSON: /api/errors/0da756a3279c28a9. Report an issue: GitHub.