What causes "Failed to set user avatar from pending URL" in RocketChat/Rocket.Chat?

From the server host, curl the logged url to see the exact status code (404/403/timeout)

Failed to set user avatar from pending URL

Error message

Failed to set user avatar from pending URL

What it means

The pending-avatars import step sets each user's avatar from the _pendingAvatarUrl stored during import using setAvatarFromServiceWithValidation; the call failed for this user and is logged per-user (the step continues and the completed counter still advances). The _pendingAvatarUrl field is left in place, so the user keeps a pending URL that can be retried.

Source

Thrown at apps/meteor/server/lib/import/pending-avatars/PendingAvatarImporter.ts:52

	}

	override async startImport(importSelection: IImporterShortSelection): Promise<ImporterProgress> {
		const pendingFileUserList = Users.findAllUsersWithPendingAvatar();
		try {
			for await (const user of pendingFileUserList) {
				try {
					const { _pendingAvatarUrl: url, name, _id } = user;

					try {
						if (!url?.startsWith('http')) {
							continue;
						}

						try {
							await setAvatarFromServiceWithValidation(_id, url, undefined, 'url');
							await Users.updateOne({ _id }, { $unset: { _pendingAvatarUrl: '' } });
						} catch (error) {
							this.logger.warn({ msg: 'Failed to set user avatar from pending URL', name, url });
						}
					} finally {
						await this.addCountCompleted(1);
					}
				} catch (error) {
					this.logger.error({ msg: 'Failed to process pending avatar for user', err: error });
				}
			}
		} catch (error) {
			// If the cursor expired, restart the method
			if (this.isCursorNotFoundError(error)) {
				this.logger.info('CursorNotFound');
				return this.startImport(importSelection);
			}

			await super.updateProgress(ProgressStep.ERROR);
			throw error;
		}

View on GitHub (pinned to b2c16d5842)

Solutions

From the server host, curl the logged url to see the exact status code (404/403/timeout)
For expired or private URLs, re-export or rehost avatars at stable public URLs, then re-run the pending-avatars step
Fix egress rules if the server cannot reach the avatar hosts
Accept the fallback (initials avatar) by unsetting _pendingAvatarUrl for the affected users

Defensive patterns

Strategy: try-catch

Validate before calling

// only queue URLs the server can actually fetch
if (!/^https?:\/\//.test(url)) continue; // already checked: only http(s) allowed
const head = await fetch(url, { method: 'HEAD' }).catch(() => undefined);
if (!head?.ok) {
	this.logger.warn({ msg: 'Skipping unreachable pending avatar', name, url, status: head?.status });
	continue;
}

Try / catch

try {
	await setAvatarFromServiceWithValidation(_id, url, undefined, 'url');
	await Users.updateOne({ _id }, { $unset: { _pendingAvatarUrl: '' } });
} catch (error) {
	this.logger.warn({ msg: 'Failed to set user avatar from pending URL', name, url });
	// _pendingAvatarUrl stays set so a later run can retry
} finally {
	await this.addCountCompleted(1);
}

Prevention

Run the avatar import step soon after export so signed avatar URLs are still valid
Ensure the server can reach external avatar hosts (egress rules, proxies)
Track per-user failures so retriable URLs are re-run instead of silently counted

When it happens

Trigger: Avatar URL returning 404/403 (expired signed Slack/S3 links, private buckets); response content-type not an image or unsupported format; image exceeding the avatar size/validation limits; server-side fetch blocked by egress rules; user record deleted meanwhile.

Common situations: Running the avatar step long after the export so signed URLs expired; servers without outbound internet; avatars hosted on intranet hosts unreachable from Rocket.Chat; oversized images failing validation.

Related errors

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