fix(actions): surface image size limit errors instead of the generic message

[pacocartones]

Summary

processImageUrl() never tells a caller that their image was too big. The size-limit passthrough in the catch block sniffs the error message for "Image size exceeds":

if (error instanceof Error && error.message.includes("Image size exceeds")) {
	throw error; // Re-throw size limit errors as-is
}

but the message getImageSizeErrorMessage() actually produces is

Image size (32.0MB) exceeds your current limit of 1MB.

The size parenthetical sits between Image size and exceeds, so the substring never matches. That branch is dead. Both remote-URL size checks — the Content-Length pre-check and the post-download body check — are swallowed and rethrown as the generic "Failed to process image from URL".

The asymmetry is what gives it away: the data URL branch throws from outside the try, so it always reported the real message. Same rejection, two different answers depending on how the image arrived.

Fix

Replace the message sniffing with a typed ImageSizeLimitError. The passthrough then keys off the type, so it cannot rot again the next time the wording changes — which is exactly how it broke.

The other two passthroughs in the same catch ("Failed to fetch image: HTTP" and "URL does not point to a valid image") also use .includes(), but those substrings do match the messages that are actually thrown, so they work today. I left them alone rather than widen this PR.

Tests

New packages/actions/src/process-image-url.spec.ts, 4 tests:

• Content-Length exceeds the limit — the pre-check path.
• downloaded body exceeds the limit — a streamed response carries no Content-Length, so the post-download check is the one that rejects.
• data URL and remote URL report the same way — pins the asymmetry that is the whole bug.
• non-size failures are still sanitized — the passthrough must stay narrow, so upstream/network detail does not leak to the caller.

In each size test the message is asserted before the type, on purpose: that is the line that fails on main, and it fails for the reason a user experiences rather than because a new export is missing.

Without the fix (source reverted to main, tests kept):

 FAIL  process-image-url.spec.ts > surfaces the size message when Content-Length exceeds the limit
AssertionError: expected 'Failed to process image from URL' to contain 'Image size (32.0MB) exceeds your curr…'

 FAIL  process-image-url.spec.ts > surfaces the size message when the downloaded body exceeds the limit
AssertionError: expected 'Failed to process image from URL' to contain 'Image size (2.0MB) exceeds your curre…'

 FAIL  process-image-url.spec.ts > reports data URL and remote URL rejections the same way
AssertionError: expected 'Failed to process image from URL' to match /^Image size \(\d+\.\d+MB\) exceeds yo…/

 Tests  3 failed | 1 passed (4)

With the fix: Tests 4 passed (4).

What I did not verify

pnpm exec vitest run packages/actions is 534 passed, 4 failed; the 4 failures are provider-key/env-inventory.spec.ts hitting ECONNREFUSED 127.0.0.1:6379. I re-ran that file on a clean main and it fails identically, so it is a missing local Redis and not this change — but I have not run the suite anywhere with the service up. tsc --noEmit, eslint and prettier --check are clean on both changed files.

Summary by CodeRabbit

• Bug Fixes
  • Improved image size-limit handling for remote and data URL images.
  • Added consistent, clearly typed errors when images exceed the allowed size.
  • Prevented unrelated image download failures from being misidentified as size-limit errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d90839eb-5080-4195-9547-e958efdf7e7f

📥 Commits

Reviewing files that changed from the base of the PR and between af282cf and f2377fa.

📒 Files selected for processing (2)

• packages/actions/src/process-image-url.spec.ts
• packages/actions/src/process-image-url.ts

---

Walkthrough

Changes

Image size-limit error handling

Layer / File(s)	Summary
Typed size-limit error flow packages/actions/src/process-image-url.ts, packages/actions/src/process-image-url.spec.ts	ImageSizeLimitError now identifies data URL, Content-Length, and downloaded-body size violations. processImageUrl rethrows this error type and sanitizes other fetch failures. Tests cover the error type, messages, response handling, and cleanup.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: steebchen

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: preserving image size limit errors instead of replacing them with a generic message.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[smakosh]

Code review

Typing the error is the right call, but as written the fix lands on /v1/images and /v1/videos only — the chat-completions path still flattens it to a 500. Findings below, most important first.

1. ImageSizeLimitError extends Error instead of RequestError, so chat completions still return a generic 500

llmgateway/packages/actions/src/process-image-url.ts

Lines 14 to 20 in f2377fa

	*/
	export class ImageSizeLimitError extends Error {
	public constructor(message: string) {
	super(message);
	this.name = "ImageSizeLimitError";
	}
	}

RequestError is already imported in this file. Because the new class isn't one, on /v1/chat/completions:

• transformGoogleMessages only preserves RequestError and otherwise rethrows a plain Error:

  llmgateway/packages/actions/src/transform-google-messages.ts

  Lines 382 to 392 in f2377fa

  	error instanceof Error ? error.message : "Unknown error";
  	// Preserve the RequestError type (and its status code) so the
  	// gateway returns a 4xx and logs a client_error row instead of
  	// treating a client-caused image failure as an unhandled 500.
  	if (error instanceof RequestError) {
  	throw new RequestError(
  	`Failed to process image: ${errorMsg}`,
  	error.statusCode,
  	);
  	}
  	throw new Error(`Failed to process image: ${errorMsg}`);

• the chat handler's typed-client-error branch doesn't match, so no client_error log row is written:

  llmgateway/apps/gateway/src/chat/chat.ts

  Lines 6362 to 6373 in f2377fa

  	);
  	} catch (e) {
  	// Surface typed pre-upstream input errors in the activity feed as a
  	// client_error. Without this, app.onError returns a 400 but no log row
  	// is written, so the user never sees the rejected request in history.
  	if (
  	e instanceof InvalidFileContentError ||
  	e instanceof UnsupportedAudioFormatError ||
  	e instanceof UnsupportedDocumentFormatError ||
  	e instanceof RequestError
  	) {
  	const statusCode = e instanceof RequestError ? e.statusCode : 400;

• app.onError falls through to 500 "Internal Server Error" plus an Unhandled error log:

  llmgateway/apps/gateway/src/app.ts

  Lines 223 to 226 in f2377fa

  	// For any other errors (non-HTTPException), return 500 Internal Server Error
  	logger.error("Unhandled error", toError(error));
  	return renderGatewayError(c, 500, "Internal Server Error");

So the user still gets an opaque 500 with the size message discarded, the request never appears in the activity feed, and every oversized user image raises a false server-error alert. extends RequestError with statusCode 400 fixes all of these at once (and also covers the aws-mantle path in prepare-request-body.ts, which has no try/catch).

2. On Anthropic and Bedrock the size error is swallowed into a placeholder, so the fix is a no-op there

llmgateway/packages/actions/src/transform-anthropic-messages.ts

Lines 117 to 127 in f2377fa

	};
	} catch (error) {
	logger.error(`Failed to fetch image ${part.image_url.url}`, {
	err: error instanceof Error ? error : new Error(String(error)),
	});
	// Fallback to text representation
	return {
	type: "text",
	text: `[Image failed to load: ${part.image_url.url}]`,
	} as TextContent;
	}

Both call sites catch every processImageUrl error and substitute [Image failed to load: <url>] (Bedrock does the same in prepare-request-body.ts). The request returns 200, the image is silently ignored, and the user is billed for the tokens without ever learning the image was too big — the same symptom, on the two chat providers that actually download images. Worth re-throwing ImageSizeLimitError from those catches.

3. The newly-surfaced message states a limit the caller doesn't have on /v1/images and /v1/videos

llmgateway/packages/actions/src/process-image-url.ts

Lines 190 to 193 in f2377fa

	if (error instanceof ImageSizeLimitError) {
	throw error; // Re-throw size limit errors as-is
	}

Both call sites use the default maxSizeMB = 20 and userPlan = null:

• llmgateway/apps/gateway/src/images/images.ts

  Lines 1069 to 1073 in f2377fa

  	const imageResults = await Promise.all(
  	imageUrls.map(async (url, index) => {
  	try {
  	return await processImageUrl(url, isProd);
  	} catch (error) {

• llmgateway/apps/gateway/src/videos/videos.ts

  Lines 4273 to 4279 in f2377fa

  	try {
  	const { data, mimeType } = await processImageUrl(
  	imageUrl,
  	process.env.NODE_ENV === "production",
  	20,
  	null,
  	);

A Pro org (100MB on chat) posting a 30MB image to /v1/images/edits now gets Image size (30.0MB) exceeds your current limit of 20MB. — a number that org doesn't have, and one that contradicts its chat limit. With userPlan null, an enterprise org also gets the non-enterprise upsell sentence. Before this change the generic message hid the wrong number; now it is user-visible, so these call sites should pass the real limit and plan.

4. Enterprise orgs are bucketed into the free cap on chat

llmgateway/apps/gateway/src/chat/chat.ts

Lines 2725 to 2732 in f2377fa

	// Get image size limits from environment variables or use defaults
	const freeLimitMB = Number(process.env.IMAGE_SIZE_LIMIT_FREE_MB) || 50;
	const proLimitMB = Number(process.env.IMAGE_SIZE_LIMIT_PRO_MB) || 100;
	// Determine max image size based on plan
	const userPlan = organization?.plan ?? "free";
	const maxImageSizeMB = userPlan === "pro" ? proLimitMB : freeLimitMB;

userPlan === "pro" ? proLimitMB : freeLimitMB puts enterprise on the free limit, and both values are forwarded to processImageUrl. Combined with the enterprise branch of getImageSizeErrorMessage, an enterprise org can now be told exceeds your current limit of 50MB. Contact us to increase your Enterprise plan limits. Pre-existing, but this PR is what makes it reach the user.

5. toFixed(1) can print a limit that equals the reported size

llmgateway/packages/actions/src/process-image-url.ts

Lines 32 to 34 in f2377fa

	let message = `Image size (${actualSizeMB.toFixed(1)}MB) exceeds your current limit of ${maxSizeMB}MB.`;

The actual size is rounded to one decimal while the limit prints as a bare integer, so anything in the ~52KB band above the limit reads Image size (1.0MB) exceeds your current limit of 1MB. ((1048577/(1024*1024)).toFixed(1) === "1.0"). Users barely over the threshold — exactly the ones who hit this — get a self-contradictory message. Rounding up would avoid it.

6. logger.error fires for what is now an ordinary client rejection

llmgateway/packages/actions/src/process-image-url.ts

Lines 184 to 193 in f2377fa

	} catch (error) {
	// Log the full error internally but sanitize the thrown error
	logger.error("Error processing image URL", {
	err: error instanceof Error ? error : new Error(String(error)),
	url: url.substring(0, 50) + "...",
	});
	if (error instanceof ImageSizeLimitError) {
	throw error; // Re-throw size limit errors as-is
	}

The error-severity log runs before the new instanceof passthrough, so every plan-limit rejection lands in error dashboards next to genuine fetch/SSRF/decode failures — and it is already logged at warn at the throw sites. Moving the logger.error below the passthrough would keep it to unexpected failures.

7. Size is checked before content type, so oversized non-images now get the wrong diagnosis

llmgateway/packages/actions/src/process-image-url.ts

Lines 135 to 155 in f2377fa

	// Check content length
	const contentLength = response.headers.get("content-length");
	if (contentLength && parseInt(contentLength, 10) > maxSizeBytes) {
	const actualSizeMB = parseInt(contentLength, 10) / (1024 * 1024);
	logger.warn("Image size exceeds limit via Content-Length", {
	contentLength,
	maxSizeMB,
	actualSizeMB,
	});
	throw new ImageSizeLimitError(
	getImageSizeErrorMessage(maxSizeMB, actualSizeMB, userPlan),
	);
	}
	const contentType = response.headers.get("content-type");
	if (!contentType || !contentType.startsWith("image/")) {
	logger.warn("Invalid content type for image URL", {
	contentType,
	url: url.substring(0, 50) + "...",
	});
	throw new Error("URL does not point to a valid image");

A 60MB application/pdf URL now reports "Image size … exceeds your current limit" rather than "URL does not point to a valid image", so the user shrinks the file and hits a completely different error on the retry. Previously both collapsed to the generic message, so the misleading specificity is new. Checking content type first resolves it.

Tests

• The fully anchored regex couples the assertion to ambient env: getImageSizeErrorMessage appends the upsell sentence when HOSTED and PAID_MODE are both "true", and neither is pinned by the vitest setup or CI, so HOSTED=true PAID_MODE=true pnpm test:unit turns this red. Dropping the $ (or clearing both vars in the test) makes it deterministic.

  llmgateway/packages/actions/src/process-image-url.spec.ts

  Lines 92 to 100 in f2377fa

  	const sizeMessage =
  	/^Image size \(\d+\.\d+MB\) exceeds your current limit of 1MB\.$/;
  	// Data URLs already reported correctly (they throw outside the try), so
  	// this asymmetry is the whole bug: same rejection, two different answers
  	// depending on how the image arrived.
  	expect((dataUrl as Error).message).toMatch(sizeMessage);
  	expect((remote as Error).message).toMatch(sizeMessage);
  	expect(remote).toBeInstanceOf(ImageSizeLimitError);

• throw new Error("expected throw") sits inside the try it guards, so it is caught by its own catch and a regression where processImageUrl stops throwing reports expected 'expected throw' to contain … instead of naming the real failure. await expect(...).rejects.toThrow(...) — used correctly in the last test — avoids the misdirection. Same shape at L68.

  llmgateway/packages/actions/src/process-image-url.spec.ts

  Lines 45 to 58 in f2377fa

  	try {
  	await processImageUrl(REMOTE_URL, false, MAX_SIZE_MB);
  	throw new Error("expected throw");
  	} catch (err) {
  	// The message is asserted before the type on purpose: this is the line
  	// that fails on the unfixed code, and it fails for the reason the user
  	// experiences ("Failed to process image from URL") rather than because
  	// a new export is missing.
  	expect((err as Error).message).toContain(
  	"Image size (32.0MB) exceeds your current limit of 1MB.",
  	);
  	expect(err).toBeInstanceOf(ImageSizeLimitError);
  	}

• Several comments narrate the pre-fix bug rather than current behaviour ("The catch block used to sniff for…", "this is the line that fails on the unfixed code"), including the class doc comment. AGENTS.md/CLAUDE.md asks for no unnecessary comments; this archaeology already lives in the PR description.

  llmgateway/packages/actions/src/process-image-url.spec.ts

  Lines 36 to 41 in f2377fa

  	// The catch block used to sniff for "Image size exceeds", which the generated
  	// message ("Image size (32.0MB) exceeds your current limit of 1MB.") never
  	// contains, so every remote-URL size rejection surfaced as the generic
  	// "Failed to process image from URL" and users were never told why.
  	it("surfaces the size message when Content-Length exceeds the limit", async () => {

Pre-existing, not this PR's job — flagging for a follow-up

Two memory hazards in the same function that this PR's tests now pin in place: the body is fully buffered before the post-download size check, so a response with no (or an understated) Content-Length bypasses the cap entirely, and the base64 conversion allocates one JS string per byte before joining.

llmgateway/packages/actions/src/process-image-url.ts

Lines 157 to 178 in f2377fa

	const arrayBuffer = await response.arrayBuffer();
	// Check actual size after download
	if (arrayBuffer.byteLength > maxSizeBytes) {
	const actualSizeMB = arrayBuffer.byteLength / (1024 * 1024);
	logger.warn("Image size exceeds limit after download", {
	size: arrayBuffer.byteLength,
	maxSizeMB,
	actualSizeMB,
	});
	throw new ImageSizeLimitError(
	getImageSizeErrorMessage(maxSizeMB, actualSizeMB, userPlan),
	);
	}
	// Convert arrayBuffer to base64 using browser-compatible API
	const uint8Array = new Uint8Array(arrayBuffer);
	const binaryString = Array.from(uint8Array, (byte) =>
	String.fromCharCode(byte),
	).join("");
	const base64 = btoa(binaryString);

Generated with Claude Code

[smakosh]

Opened #3480 which builds directly on this branch — your commit is preserved there, plus a Co-authored-by trailer on the follow-up.

The main addition is making ImageSizeLimitError extend RequestError so the fix reaches /v1/chat/completions too, along with the message-accuracy and test points from the review above. Leaving this open for you; happy to close it as superseded once #3480 lands if you'd rather not rework it.

[steebchen]

Thanks for the fix and the thorough write-up, @pacocartones — the diagnosis was spot on. Superseded by #3481, which carries your commit as-is and additionally addresses the review findings above (the error is now a RequestError so chat completions return a 400 instead of a 500, Anthropic/Bedrock no longer swallow it into a placeholder, and the image/video call sites report the correct limits). Closing this one in favor of #3481.

---

Generated by Claude Code