RocketChat/Rocket.Chat · error · Error

apps-engine-not-loaded

apps-engine-not-loaded

Error message

apps-engine-not-loaded

What it means

getProviderManager requires the Apps Engine to be loaded (Apps.self.isLoaded()); calling outbound metadata/send before the apps subsystem finishes loading throws 'apps-engine-not-loaded'. The state is transient — it clears once apps finish loading at startup.

Solutions

  1. Retry with backoff until Apps.self.isLoaded() is true (a few seconds at most)
  2. Sequence startup-dependent work after the apps-loaded signal instead of at boot
  3. If it never loads, inspect apps-engine logs for load failures (broken app, missing dependency)

Example fix

// before
await outboundMessageProvider.getProviderMetadata(providerId); // during startup → apps-engine-not-loaded

// after
while (!Apps.self?.isLoaded()) {
  await sleep(500);
}
await outboundMessageProvider.getProviderMetadata(providerId);
Defensive patterns

Strategy: retry

Validate before calling

import { Apps } from '@rocket.chat/apps';

if (!Apps.self?.isLoaded()) {
  // transient startup state: wait for the apps engine before touching outbound APIs
  await new Promise((resolve) => Apps.self?.once && Apps.self.once('loaded', resolve));
}
await outboundMessageProvider.getProviderMetadata(providerId);

Try / catch

for (let attempt = 0; attempt < 10; attempt++) {
  try {
    return await outboundMessageProvider.getProviderMetadata(providerId);
  } catch (error) {
    if (error instanceof Error && error.message === 'apps-engine-not-loaded' && attempt < 9) {
      await sleep(1000 * (attempt + 1)); // startup race: engine loads within seconds
      continue;
    }
    throw error;
  }
}

Prevention

When it happens

Trigger: Omnichannel outbound endpoints hit during the server startup window before AppsEngine reports loaded; or with the apps subsystem disabled/failing to load.

Common situations: Health-check or warmup scripts calling the API immediately after boot; slow app installs delaying readiness; a request racing the apps-loaded event.

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/67111497beb83880. Report an issue: GitHub.

Appendix: source

Thrown at apps/meteor/ee/server/api/v1/omnichannel/lib/outbound.ts:48

		if (type !== undefined && !this.isProviderValid(type)) {
			throw new Error('Invalid type');
		}

		return this.provider.getOutboundMessageProviders(type);
	}

	public getProviderMetadata(providerId: string): Promise<IOutboundProviderMetadata> {
		const provider = this.provider.findOneByProviderId(providerId);
		if (!provider) {
			throw new Error('error-invalid-provider');
		}

		return this.getProviderManager().getProviderMetadata(provider.appId, provider.type);
	}

	private getProviderManager() {
		if (!Apps.self?.isLoaded()) {
			throw new Error('apps-engine-not-loaded');
		}

		const manager = Apps.self?.getManager()?.getOutboundCommunicationProviderManager();
		if (!manager) {
			throw new Error('apps-engine-not-configured-correctly');
		}

		return manager;
	}

	public sendMessage(providerId: string, message: IOutboundMessage) {
		const provider = this.provider.findOneByProviderId(providerId);
		if (!provider) {
			throw new Error('error-invalid-provider');
		}

		return this.getProviderManager().sendOutboundMessage(provider.appId, provider.type, message);
	}

View on GitHub (pinned to b2c16d5842)