Add error handling improvements for upload-media

packages/upload-media/README.md

@@ -61,6 +61,8 @@ _Parameters_
 
 Cancels an item in the queue based on an error.
 
+For retryable errors (network failures, server errors, etc.), the item is automatically retried with exponential backoff up to MAX_RETRIES times before permanently failing.
+
 _Parameters_
 
 -   _id_ `QueueItemId`: Item ID.
@@ -71,6 +73,8 @@ _Parameters_
 
 Retries a failed item in the queue.
 
+Resets the item's operations to re-prepare from scratch, since the operation list is consumed as operations complete.
+
 _Parameters_
 
 -   _id_ `QueueItemId`: Item ID.

packages/upload-media/src/error-messages.ts

@@ -0,0 +1,228 @@
+/**
+ * User-friendly error messages for upload failures.
+ *
+ * Provides localized, human-readable messages for all error codes
+ * with actionable guidance for users.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { __, sprintf } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { ErrorCode } from './upload-error';
+
+/**
+ * Configuration for an error message.
+ */
+export interface ErrorMessageConfig {
+	/** Short title describing the error type. */
+	title: string;
+	/** Detailed description of what happened. */
+	description: string;
+	/** Optional actionable guidance for the user. */
+	action?: string;
+}
+
+/**
+ * Gets a user-friendly error message configuration for an error code.
+ *
+ * @param code     The error code from UploadError.
+ * @param fileName The name of the file that failed to upload.
+ * @return Error message configuration with title, description, and action.
+ */
+export function getErrorMessage(
+	code: string,
+	fileName: string
+): ErrorMessageConfig {
+	const messages: Record< string, ErrorMessageConfig > = {
+		[ ErrorCode.NETWORK_ERROR ]: {
+			title: __( 'Network error' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'Failed to upload "%s" due to a network issue.' ),
+				fileName
+			),
+			action: __( 'Check your internet connection and try again.' ),
+		},
+		[ ErrorCode.TIMEOUT_ERROR ]: {
+			title: __( 'Upload timed out' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'The upload of "%s" took too long.' ),
+				fileName
+			),
+			action: __(
+				'Try uploading a smaller file or check your connection.'
+			),
+		},
+		[ ErrorCode.SERVER_ERROR ]: {
+			title: __( 'Server error' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'The server encountered an error processing "%s".' ),
+				fileName
+			),
+			action: __( 'Please try again later.' ),
+		},
+		[ ErrorCode.FILE_TOO_LARGE ]: {
+			title: __( 'File too large' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( '"%s" exceeds the maximum upload size.' ),
+				fileName
+			),
+			action: __( 'Please reduce the file size and try again.' ),
+		},
+		[ ErrorCode.INVALID_MIME_TYPE ]: {
+			title: __( 'Unsupported file type' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( '"%s" is not a supported file type.' ),
+				fileName
+			),
+			action: __( 'Please upload a different file format.' ),
+		},
+		[ ErrorCode.INVALID_IMAGE_DIMENSIONS ]: {
+			title: __( 'Invalid image dimensions' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( '"%s" does not match the expected dimensions.' ),
+				fileName
+			),
+			action: __(
+				'The image size does not match the target thumbnail size.'
+			),
+		},
+		[ ErrorCode.PERMISSION_DENIED ]: {
+			title: __( 'Permission denied' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'You do not have permission to upload "%s".' ),
+				fileName
+			),
+			action: __( 'Please contact your site administrator.' ),
+		},
+		[ ErrorCode.NOT_FOUND ]: {
+			title: __( 'Not found' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'The upload destination for "%s" was not found.' ),
+				fileName
+			),
+			action: __( 'Please refresh the page and try again.' ),
+		},
+		[ ErrorCode.VALIDATION_ERROR ]: {
+			title: __( 'Validation failed' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( '"%s" failed validation.' ),
+				fileName
+			),
+			action: __( 'Please check the file and try again.' ),
+		},
+		[ ErrorCode.IMAGE_TRANSCODING_ERROR ]: {
+			title: __( 'Image processing failed' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'Failed to process "%s".' ),
+				fileName
+			),
+			action: __( 'The image may be corrupted. Try a different file.' ),
+		},
+		[ ErrorCode.IMAGE_ROTATION_ERROR ]: {
+			title: __( 'Image rotation failed' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'Failed to rotate "%s".' ),
+				fileName
+			),
+			action: __( 'The image may be corrupted. Try a different file.' ),
+		},
+		[ ErrorCode.VIPS_WORKER_ERROR ]: {
+			title: __( 'Image processing error' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'An error occurred while processing "%s".' ),
+				fileName
+			),
+			action: __( 'Please try again.' ),
+		},
+		[ ErrorCode.MEMORY_ERROR ]: {
+			title: __( 'Not enough memory' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'Not enough memory to process "%s".' ),
+				fileName
+			),
+			action: __(
+				'Try closing other tabs or uploading a smaller image.'
+			),
+		},
+		[ ErrorCode.ABORTED ]: {
+			title: __( 'Upload cancelled' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'The upload of "%s" was cancelled.' ),
+				fileName
+			),
+		},
+		[ ErrorCode.GENERAL ]: {
+			title: __( 'Upload failed' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'Failed to upload "%s".' ),
+				fileName
+			),
+			action: __( 'Please try again.' ),
+		},
+	};
+
+	return (
+		messages[ code ] || {
+			title: __( 'Upload failed' ),
+			description: sprintf(
+				/* translators: %s: file name */
+				__( 'Failed to upload "%s".' ),
+				fileName
+			),
+			action: __( 'Please try again.' ),
+		}
+	);
+}
+
+/**
+ * Gets a short retry message for displaying retry status.
+ *
+ * @param retryCount The current retry attempt number.
+ * @param maxRetries The maximum number of retries allowed.
+ * @return A localized message about the retry attempt.
+ */
+export function getRetryMessage(
+	retryCount: number,
+	maxRetries: number
+): string {
+	return sprintf(
+		/* translators: 1: current attempt number, 2: maximum attempts */
+		__( 'Retrying\u2026 (attempt %1$d of %2$d)' ),
+		retryCount,
+		maxRetries
+	);
+}
+
+/**
+ * Gets a message indicating that all retries have been exhausted.
+ *
+ * @param maxRetries The maximum number of retries that were attempted.
+ * @return A localized message about exhausted retries.
+ */
+export function getMaxRetriesExceededMessage( maxRetries: number ): string {
+	return sprintf(
+		/* translators: %d: number of retry attempts */
+		__( 'Upload failed after %d attempts.' ),
+		maxRetries
+	);
+}

packages/upload-media/src/store/actions.ts

@@ -24,14 +24,20 @@ import type {
 	RetryItemAction,
 	State,
 } from './types';
-import { Type } from './types';
+import { OperationType, Type } from './types';
 import type {
 	addItem,
 	processItem,
 	removeItem,
 	revokeBlobUrls,
 } from './private-actions';
+import {
+	MAX_RETRIES,
+	BASE_RETRY_DELAY_MS,
+	MAX_RETRY_DELAY_MS,
+} from './constants';
 import { vipsCancelOperations } from './utils';
+import { UploadError } from '../upload-error';
 import { validateMimeType } from '../validate-mime-type';
 import { validateMimeTypeForUser } from '../validate-mime-type-for-user';
 import { validateFileSize } from '../validate-file-size';
@@ -138,6 +144,10 @@ export function addItems( {
 /**
  * Cancels an item in the queue based on an error.
  *
+ * For retryable errors (network failures, server errors, etc.), the item
+ * is automatically retried with exponential backoff up to MAX_RETRIES times
+ * before permanently failing.
+ *
  * @param id     Item ID.
  * @param error  Error instance.
  * @param silent Whether to cancel the item silently,
@@ -158,6 +168,41 @@ export function cancelItem( id: QueueItemId, error: Error, silent = false ) {
 			return;
 		}
 
+		// Auto-retry retryable errors with exponential backoff.
+		const retryCount = item.retryCount ?? 0;
+		if (
+			error instanceof UploadError &&
+			error.isRetryable &&
+			retryCount < MAX_RETRIES
+		) {
+			const delay = Math.min(
+				BASE_RETRY_DELAY_MS * Math.pow( 2, retryCount ),
+				MAX_RETRY_DELAY_MS
+			);
+
+			// Mark as retrying (increments retryCount, clears error).
+			dispatch< RetryItemAction >( {
+				type: Type.RetryItem,
+				id,
+			} );
+
+			// Reset operations to re-prepare the item from scratch,
+			// since the operation list is consumed as operations complete.
+			dispatch( {
+				type: Type.OperationFinish,
+				id,
+				item: {
+					operations: [ OperationType.Prepare ],
+					currentOperation: undefined,
+				},
+			} );
+
+			// Wait with exponential backoff, then re-process.
+			await new Promise( ( resolve ) => setTimeout( resolve, delay ) );
+			dispatch.processItem( id );
+			return;
+		}
+
 		item.abortController?.abort();
 
 		// Cancel any ongoing vips operations for this item.
@@ -167,7 +212,6 @@ export function cancelItem( id: QueueItemId, error: Error, silent = false ) {
 			const { onError } = item;
 			onError?.( error ?? new Error( 'Upload cancelled' ) );
 			if ( ! onError && error ) {
-				// TODO: Find better way to surface errors with sideloads etc.
 				// eslint-disable-next-line no-console -- Deliberately log errors here.
 				console.error( 'Upload cancelled', error );
 			}
@@ -191,6 +235,9 @@ export function cancelItem( id: QueueItemId, error: Error, silent = false ) {
 /**
  * Retries a failed item in the queue.
  *
+ * Resets the item's operations to re-prepare from scratch,
+ * since the operation list is consumed as operations complete.
+ *
  * @param id Item ID.
  */
 export function retryItem( id: QueueItemId ) {
@@ -211,6 +258,16 @@ export function retryItem( id: QueueItemId ) {
 			id,
 		} );
 
+		// Reset operations to re-prepare the item from scratch.
+		dispatch( {
+			type: Type.OperationFinish,
+			id,
+			item: {
+				operations: [ OperationType.Prepare ],
+				currentOperation: undefined,
+			},
+		} );
+
 		dispatch.processItem( id );
 	};
 }

packages/upload-media/src/store/constants.ts

@@ -28,3 +28,19 @@ export const CLIENT_SIDE_SUPPORTED_MIME_TYPES: readonly string[] = [
 	'image/webp',
 	'image/avif',
 ] as const;
+
+/**
+ * Maximum number of automatic retry attempts for retryable errors.
+ */
+export const MAX_RETRIES = 3;
+
+/**
+ * Base delay in milliseconds for exponential backoff between retries.
+ * Actual delay = BASE_RETRY_DELAY_MS * 2^(retryCount - 1), capped at MAX_RETRY_DELAY_MS.
+ */
+export const BASE_RETRY_DELAY_MS = 1000;
+
+/**
+ * Maximum delay in milliseconds between retries.
+ */
+export const MAX_RETRY_DELAY_MS = 10000;