Descriptive image error (#9352)

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
Co-authored-by: Princesseuh <3019731+Princesseuh@users.noreply.github.com>

.changeset/famous-cars-sell.md

@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Add a more descriptive error message when image conversion fails

packages/astro/package.json

@@ -153,7 +153,7 @@
     "mime": "^3.0.0",
     "ora": "^7.0.1",
     "p-limit": "^5.0.0",
-    "p-queue": "^7.4.1",
+    "p-queue": "^8.0.1",
     "path-to-regexp": "^6.2.1",
     "preferred-pm": "^3.1.2",
     "probe-image-size": "^7.2.3",

packages/astro/src/assets/build/generate.ts

@@ -6,6 +6,8 @@ import type { AstroConfig } from '../../@types/astro.js';
 import type { BuildPipeline } from '../../core/build/buildPipeline.js';
 import { getOutDirWithinCwd } from '../../core/build/common.js';
 import { getTimeStat } from '../../core/build/util.js';
+import { AstroError } from '../../core/errors/errors.js';
+import { AstroErrorData } from '../../core/errors/index.js';
 import type { Logger } from '../../core/logger/core.js';
 import { isRemotePath, prependForwardSlash } from '../../core/path.js';
 import { isServerLikeOutput } from '../../prerender/utils.js';
@@ -103,9 +105,11 @@ export async function generateImagesForPath(
 	const originalImageData = await loadImage(originalFilePath, env);
 
 	for (const [_, transform] of transformsAndPath.transforms) {
-		queue.add(async () =>
-			generateImage(originalImageData, transform.finalPath, transform.transform)
-		);
+		await queue
+			.add(async () => generateImage(originalImageData, transform.finalPath, transform.transform))
+			.catch((e) => {
+				throw e;
+			});
 	}
 
 	// In SSR, we cannot know if an image is referenced in a server-rendered page, so we can't delete anything
@@ -207,13 +211,27 @@ export async function generateImagesForPath(
 		};
 
 		const imageService = (await getConfiguredImageService()) as LocalImageService;
-		resultData.data = (
-			await imageService.transform(
-				originalImage.data,
-				{ ...options, src: originalImagePath },
-				env.imageConfig
-			)
-		).data;
+
+		try {
+			resultData.data = (
+				await imageService.transform(
+					originalImage.data,
+					{ ...options, src: originalImagePath },
+					env.imageConfig
+				)
+			).data;
+		} catch (e) {
+			const error = new AstroError(
+				{
+					...AstroErrorData.CouldNotTransformImage,
+					message: AstroErrorData.CouldNotTransformImage.message(originalFilePath),
+				},
+				undefined,
+				{ cause: e }
+			);
+
+			throw error;
+		}
 
 		try {
 			// Write the cache entry

packages/astro/src/assets/endpoint/generic.ts

@@ -71,6 +71,7 @@ export const GET: APIRoute = async ({ request }) => {
 			},
 		});
 	} catch (err: unknown) {
+		console.error('Could not process image request:', err);
 		return new Response(`Server Error: ${err}`, { status: 500 });
 	}
 };

packages/astro/src/assets/endpoint/node.ts

@@ -89,6 +89,7 @@ export const GET: APIRoute = async ({ request }) => {
 			},
 		});
 	} catch (err: unknown) {
+		console.error('Could not process image request:', err);
 		return new Response(`Server Error: ${err}`, { status: 500 });
 	}
 };

packages/astro/src/assets/internal.ts

@@ -17,7 +17,7 @@ export async function getConfiguredImageService(): Promise<ImageService> {
 			'virtual:image-service'
 		).catch((e) => {
 			const error = new AstroError(AstroErrorData.InvalidImageService);
-			(error as any).cause = e;
+			error.cause = e;
 			throw error;
 		});
 

packages/astro/src/core/errors/errors-data.ts

@@ -706,6 +706,23 @@ export const MarkdownImageNotFound = {
 	hint: 'This is often caused by a typo in the image path. Please make sure the file exists, and is spelled correctly.',
 } satisfies ErrorData;
 
+/**
+ * @docs
+ * @see
+ * - [Images](https://docs.astro.build/en/guides/images/)
+ * @description
+ * Astro could not transform one of your images. Often, this is caused by a corrupted or malformed image. Re-exporting the image from your image editor may fix this issue.
+ *
+ * Depending on the image service you are using, the stack trace may contain more information on the specific error encountered.
+ */
+export const CouldNotTransformImage = {
+	name: 'CouldNotTransformImage',
+	title: 'Could not transform image.',
+	message: (imagePath: string) =>
+		`Could not transform image \`${imagePath}\`. See the stack trace for more information.`,
+	hint: 'This is often caused by a corrupted or malformed image. Re-exporting the image from your image editor may fix this issue.',
+} satisfies ErrorData;
+
 /**
  * @docs
  * @description