What causes "error-room-onHold" in RocketChat/Rocket.Chat?

Take the room off hold (resume the on-hold conversation) before transferring it to the queue.

RocketChat/Rocket.Chat · error · Meteor.Error

error-room-onHold

error-room-onHold

Error message

error-room-onHold

What it means

Second guard in returnRoomAsInquiry: rooms flagged onHold cannot be returned to the queue and raise Meteor.Error('error-room-onHold'). An on-hold room must leave the hold state before it can re-enter the queue.

Source

Thrown at apps/meteor/server/lib/omnichannel/rooms.ts:227

		if (responses[2]?.modifiedCount) {
			await notifyOnSubscriptionChangedByRoomId(rid);
		}
	}

	void notifyOnRoomChangedById(roomData._id);

	return true;
}

export async function returnRoomAsInquiry(room: IOmnichannelRoom, departmentId?: string, overrideTransferData: Partial<TransferData> = {}) {
	livechatLogger.debug({ msg: 'Transferring room to queue', scope: departmentId ? 'department' : undefined, room });
	if (!room.open) {
		throw new Meteor.Error('room-closed', 'Room closed');
	}

	if (room.onHold) {
		throw new Meteor.Error('error-room-onHold');
	}

	if (!(await Omnichannel.isWithinMACLimit(room))) {
		throw new Meteor.Error('error-mac-limit-reached');
	}

	if (!room.servedBy) {
		return false;
	}

	const user = await Users.findOneById(room.servedBy._id);
	if (!user?._id) {
		throw new Meteor.Error('error-invalid-user');
	}

	const inquiry = await LivechatInquiry.findOne({ rid: room._id });
	if (!inquiry) {
		return false;

View on GitHub (pinned to b2c16d5842)

Solutions

Take the room off hold (resume the on-hold conversation) before transferring it to the queue.
Filter onHold rooms out of bulk transfer/return jobs.
Check the room's On-Hold conversations state (Administration > Omnichannel) to understand why it was held.

Example fix

// before
await returnRoomAsInquiry(room, departmentId); // throws error-room-onHold

// after
if (room.onHold) {
	throw new Error('resume the on-hold conversation before transferring');
}
await returnRoomAsInquiry(room, departmentId);

Defensive patterns

Strategy: validation

Validate before calling

if (room.onHold) {
	throw new Error('resume the on-hold conversation before returning it to the queue');
}
await returnRoomAsInquiry(room, departmentId);

Type guard

const isReturnableToQueue = (room: Pick<IOmnichannelRoom, 'open' | 'onHold'>): boolean =>
	room.open === true && room.onHold !== true;

Try / catch

try {
	await returnRoomAsInquiry(room, departmentId);
} catch (err) {
	if (err instanceof Meteor.Error && err.error === 'error-room-onHold') {
		// prompt the agent to resume the on-hold room first
		return;
	}
	throw err;
}

Prevention

Show on-hold status in transfer lists so agents filter those rooms.
Bulk automation must skip rooms with onHold set.
Understand the on-hold lifecycle (auto on-hold after inactivity) before building transfer tooling.

When it happens

Trigger: Returning a room to the queue while it is on hold — the visitor stopped responding and the on-hold conversations feature flagged the room.

Common situations: On-hold chats still visible in transfer lists; bulk-transfer automation that does not filter onHold rooms; agents unaware a room was auto-placed on hold.

Related errors

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