RocketChat/Rocket.Chat · warning · Meteor.Error

error-shield-disabled

error-shield-disabled

Error message

This shield type is disabled

What it means

Thrown by GET /api/v1/shield.svg when the requested type query parameter is not included in the API_Shield_Types setting (and that setting is not '*'). The allowed types are a comma-separated whitelist — if 'user' or 'channel' is excluded, requesting it produces this error.

Source

Thrown at apps/meteor/server/api/v1/misc.ts:237

	async function action() {
		const { type, icon } = this.queryParams;
		let { channel, name } = this.queryParams;
		if (!settings.get('API_Enable_Shields')) {
			throw new Meteor.Error('error-endpoint-disabled', 'This endpoint is disabled', {
				route: '/api/v1/shield.svg',
			});
		}

		const types = settings.get<string>('API_Shield_Types');
		if (
			type &&
			types !== '*' &&
			!types
				.split(',')
				.map((t: string) => t.trim())
				.includes(type)
		) {
			throw new Meteor.Error('error-shield-disabled', 'This shield type is disabled', {
				route: '/api/v1/shield.svg',
			});
		}
		const hideIcon = icon === 'false';
		if (hideIcon && !name?.trim()) {
			return API.v1.failure('Name cannot be empty when icon is hidden');
		}

		let text;
		let backgroundColor = '#4c1';
		switch (type) {
			case 'online':
				if (Date.now() - onlineCacheDate > cacheInvalid) {
					onlineCache = await Users.countUsersNotOffline();
					onlineCacheDate = Date.now();
				}

				text = `${onlineCache} ${i18n.t('Online')}`;

View on GitHub (pinned to f9d3ec372b)

Solutions

  1. Add the desired type to the API_Shield_Types setting (e.g., 'online,channel,user'), or set it to '*' for all types.
  2. Use a shield type that is in the current allowed list.
  3. Check the current setting via GET /api/v1/settings/API_Shield_Types before requesting a specific type.

Example fix

// before: API_Shield_Types = "online,channel"
// request shield.svg?type=user -> error
// after: update the setting
PUT /api/v1/settings/API_Shield_Types { "value": "online,channel,user" }
Defensive patterns

Strategy: validation

Validate before calling

// Fetch allowed shield types and validate the requested type before calling
const res = await fetch(`${baseUrl}/api/v1/settings/API_Shield_Types`, {
  headers: authHeaders
}).then(r => r.json());

const allowedTypes = res.value === '*' ? ['online', 'channel', 'user'] : res.value.split(',').map(t => t.trim());
if (!allowedTypes.includes(requestedType)) {
  throw new Error(`Shield type '${requestedType}' is not allowed. Allowed: ${allowedTypes.join(', ')}`);
}

Type guard

function isAllowedShieldType(type: string, allowedTypes: string | string[]): boolean {
  if (allowedTypes === '*') return true;
  const list = typeof allowedTypes === 'string' ? allowedTypes.split(',').map(t => t.trim()) : allowedTypes;
  return list.includes(type);
}

Try / catch

try {
  const svg = await fetchShieldBadge(type);
} catch (e) {
  if (e.error === 'error-shield-disabled') {
    console.warn(`Shield type '${type}' is disabled. Check API_Shield_Types setting.`);
    return;
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling GET /api/v1/shield.svg?type=user when API_Shield_Types is set to 'online,channel' (not including 'user' or '*'). Or requesting any type not in the configured list.

Common situations: Admin restricted shield types for privacy (e.g., disabled 'user' type to prevent exposing individual user statuses); typo in the type parameter; the setting was changed and the client is using an outdated type.

Related errors

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