RocketChat/Rocket.Chat · error · Meteor.Error
no-agent-online
no-agent-online
Error message
no-agent-online
What it means
Thrown by the External routing method when Rocket.Chat delegates agent selection to an external queue service. getNextAgent fires 10 parallel requests to the Livechat_External_Queue_URL; every request that fails or returns nothing is filtered out with Boolean, and if nothing remains it throws 'no-agent-online' ('Sorry, no online agents'). The catch block logs the underlying error to SystemLogger and rethrows.
Source
Thrown at apps/meteor/server/lib/omnichannel/routing/External.ts:33
previewRoom: false,
showConnecting: false,
showQueue: false,
showQueueLink: false,
returnQueue: false,
enableTriggerAction: true,
autoAssignAgent: true,
};
}
async getNextAgent(department?: string, ignoreAgentId?: string): Promise<SelectedAgent | null | undefined> {
const promises = [];
for (let i = 0; i < 10; i++) {
promises.push(this.getAgentFromExternalQueue(department, ignoreAgentId));
}
try {
const results = (await Promise.all(promises)).filter(Boolean);
if (!results.length) {
throw new Meteor.Error('no-agent-online', 'Sorry, no online agents');
}
return results[0];
} catch (err) {
SystemLogger.error({ msg: 'Error requesting agent from external queue.', err });
throw err;
}
}
private async getAgentFromExternalQueue(department?: string, ignoreAgentId?: string): Promise<SelectedAgent | null | undefined> {
try {
const request = await fetch(`${settings.get('Livechat_External_Queue_URL')}`, {
headers: {
'User-Agent': 'RocketChat Server',
'Accept': 'application/json',
'X-RocketChat-Secret-Token': settings.get('Livechat_External_Queue_Token'),
},
params: {
...(department && { departmentId: department }),View on GitHub (pinned to b2c16d5842)
Solutions
- Verify the Livechat_External_Queue_URL setting value in Admin > Omnichannel > Routing
- curl the endpoint from the Rocket.Chat server and confirm it returns a valid agent (SelectedAgent-shaped) JSON body
- Check SystemLogger for 'Error requesting agent from external queue.' entries containing the real err (DNS, timeout, 401, etc.)
- Confirm the external queue actually has online agents for that department
- If the external service is permanently unavailable, switch Livechat_Routing_Method back to Auto_Selection or Load_Balancing as a fallback
Defensive patterns
Strategy: fallback
Validate before calling
// health-check the external queue before relying on it
import { settings } from '../settings';
async function externalQueueHealthy(): Promise<boolean> {
const url = settings.get<string>('Livechat_External_Queue_URL');
if (!url) return false;
try {
const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
return res.ok;
} catch {
return false;
}
} Type guard
type SelectedAgent = { agentId: string; username?: string };
function isSelectedAgent(v: unknown): v is SelectedAgent {
return typeof v === 'object' && v !== null && typeof (v as SelectedAgent).agentId === 'string';
} Try / catch
try {
agent = await routingManager.getNextAgent(departmentId);
} catch (err) {
if (err instanceof Meteor.Error && err.error === 'no-agent-online') {
// degrade gracefully: fall back to internal routing or queue for retry
agent = await internalAutoSelection(departmentId);
} else {
throw err;
}
} Prevention
- Monitor the external queue endpoint with a synthetic probe and page before it goes down
- Validate Livechat_External_Queue_URL from the server network (curl/fetch) after every settings change
- Log and alert on SystemLogger 'Error requesting agent from external queue' — it carries the real cause
- Document the expected SelectedAgent JSON contract with the external system owners
When it happens
Trigger: Omnichannel routing method set to 'External' (Livechat_Routing_Method) and a new inquiry needs an agent, while the external queue endpoint is unreachable, returns non-2xx/an error (getAgentFromExternalQueue swallows these and returns null), returns an empty agent payload, or the external system genuinely has no online agents.
Common situations: Livechat_External_Queue_URL misconfigured (wrong URL, missing protocol or path), the external queue service is down or restarting, network egress blocked from the Rocket.Chat server, response schema mismatch with the expected SelectedAgent JSON, or all agents offline in the external system.
Related errors
- App package download failed
- App metadata download failed
- error-invalid-webhook-response
- error-no-agents-available-for-service-on-department
- error-agent-is-locked
AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18).
Data as JSON: /api/errors/d4a8ac1ddb93e2a6.
Report an issue: GitHub.