Add error handling improvements for upload-media

[adamsilverstein]

Fixes #74366

Summary

Adds error classification + logging + instrumentation to @wordpress/upload-media. Split from the original combined PR per reviewer feedback — auto-retry/scheduling lands in a follow-up PR.

What's in this PR

Error classification (wired up)

• ErrorCode enum covering every code currently thrown by the package (EMPTY_FILE, SIZE_ABOVE_LIMIT, MIME_TYPE_NOT_SUPPORTED, MIME_TYPE_NOT_ALLOWED_FOR_USER, HEIC_DECODE_ERROR, IMAGE_TRANSCODING_ERROR, IMAGE_ROTATION_ERROR, MEDIA_TRANSCODING_ERROR), plus aspirational retry-targets (NETWORK_ERROR, TIMEOUT_ERROR, SERVER_ERROR) kept for the retry follow-up.
• UploadError#isRetryable getter backed by a RETRYABLE_CODES allowlist.
• All existing throw sites (validate-file-size, validate-mime-type, validate-mime-type-for-user, store/private-actions) migrated from bare string codes to ErrorCode enum members.
• error-messages.ts — localized, i18n-ready message map (title / description / optional action) covering every enum code with a sane fallback.
• ErrorCode, getErrorMessage, and the ErrorMessageConfig type are now re-exported from packages/upload-media/src/index.ts so consumers (Notice UI, block-editor) can render friendly messages off a raw UploadError.

Dev-only logging via @wordpress/warning

• cancelItem now emits deduplicated warnings on silent cancels, missing onError handlers, and batch completion.
• Only fires under SCRIPT_DEBUG, so there's no production overhead.

Performance instrumentation (User Timings API)

• store/utils/debug-logger.ts exposes a measure() helper that writes entries to a custom "Upload Media" track visible in the DevTools Performance panel.
• Instrumented: uploadItem, sideloadItem, resizeCropItem, rotateItem, transcodeImageItem.
• Gated on globalThis.SCRIPT_DEBUG (matching the @wordpress/warning pattern), so production builds skip the performance.measure call entirely.

Incidental fix

• uploadItem now guards against double-dispatch of finishOperation when both onFileChange and onSuccess fire for the same attachment (idempotent finishUpload closure).

Files

Modified

• packages/upload-media/src/upload-error.ts — ErrorCode enum + isRetryable getter
• packages/upload-media/src/validate-file-size.ts — use ErrorCode
• packages/upload-media/src/validate-mime-type.ts — use ErrorCode
• packages/upload-media/src/validate-mime-type-for-user.ts — use ErrorCode
• packages/upload-media/src/store/actions.ts — warning() calls in cancelItem
• packages/upload-media/src/store/private-actions.ts — measure() instrumentation + finishUpload idempotency + ErrorCode
• packages/upload-media/src/store/test/actions.ts — assert warning() fires
• packages/upload-media/src/store/test/reducer.ts — incidental coverage for PauseQueue, ResumeQueue, CacheBlobUrl, RevokeBlobUrls
• packages/upload-media/src/index.ts — export ErrorCode, getErrorMessage, ErrorMessageConfig
• packages/upload-media/package.json — add @wordpress/warning dep
• packages/upload-media/tsconfig.json — add warning project reference
• packages/upload-media/CHANGELOG.md — entries under Unreleased
• .gitignore — ignore test-results/

Added

• packages/upload-media/src/error-messages.ts — localized message map + getErrorMessage()
• packages/upload-media/src/store/utils/debug-logger.ts — measure() helper

Test plan

• All existing unit tests pass (188 tests across @wordpress/upload-media)
• tsc --noEmit clean across the package
• prettier --check clean on all changed files
• Manual: upload with SCRIPT_DEBUG = true, verify @wordpress/warning surfaces on cancel and batch completion
• Manual: with SCRIPT_DEBUG = true, confirm "Upload Media" track appears in DevTools Performance panel for an upload with sub-size sideloads
• Manual: upload a file over maxUploadFileSize, verify the resulting UploadError passed to onError has code === ErrorCode.SIZE_ABOVE_LIMIT and isRetryable === false

Out of scope (follow-up PR)

• Automatic retry scheduling (scheduleRetry, executeRetry, retry-timer map). The existing manual retryItem action, retryCount field, and RetryItem reducer (all pre-dating this PR) remain on trunk and are unchanged here.
• Wrapping network/fetch failures as NETWORK_ERROR / TIMEOUT_ERROR / SERVER_ERROR so isRetryable has real producers. The enum is already in place for when that lands.
• Consumer UX (Notice / upload list row) that renders getErrorMessage().

[github-actions]

Size Change: +1.07 kB (+0.01%)

Total Size: 8.21 MB

📦 View Changed

Filename	Size	Change
build/scripts/upload-media/index.min.js	13.2 kB	+1.07 kB (+8.79%)	🔍

_{compressed-size-action}

[github-actions]

Flaky tests detected in 0f98395.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27035639982
📝 Reported issues:

• [Flaky Test] Custom Completer: should cancel option selection via Escape keypress event #48887 in /test/e2e/specs/editor/various/autocomplete-and-mentions.spec.js
• [Flaky Test] should allow user to add and remove multiple local font files #78760 in /test/e2e/specs/admin/font-library.spec.js

[Copilot]

Pull request overview

This PR implements comprehensive error handling and retry logic for the upload-media package to address GitHub Issue #74366. The implementation adds an error classification system with 16 error types, automatic retry with exponential backoff for transient failures, user-friendly localized error messages, and retry state management with a new ItemStatus.PendingRetry status.

Changes:

• Added ErrorCode enum with 16 error types categorized as retryable (network, timeout, server, VIPS worker errors) and non-retryable (validation, permission, file size, MIME type errors)
• Implemented automatic retry with exponential backoff and jitter for failed uploads, with configurable retry settings (default: 3 attempts, 1s-30s delays, 2x multiplier)
• Created comprehensive error message system with localized, actionable user guidance for all error types

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/upload-media/src/upload-error.ts	Added ErrorCode enum and isRetryable getter to classify errors
packages/upload-media/src/error-messages.ts	New file providing user-friendly i18n error messages for all error codes
packages/upload-media/src/store/utils/retry.ts	New file with exponential backoff calculation and error classification logic
packages/upload-media/src/store/utils/debug-logger.ts	Added logging functions for retry scheduling, execution, and max retries exceeded
packages/upload-media/src/store/types.ts	Added RetrySettings, ScheduleRetryAction, ItemStatus.PendingRetry, and retry-related QueueItem fields
packages/upload-media/src/store/constants.ts	Added retry configuration constants (max attempts, delays, multiplier, jitter)
packages/upload-media/src/store/reducer.ts	Added ScheduleRetry case and default retry settings initialization
packages/upload-media/src/store/actions.ts	Modified cancelItem to check retry eligibility, added scheduleRetry and executeRetry actions
packages/upload-media/src/store/private-selectors.ts	Added selectors for retry state (pending items, retry timestamp, retry count, max retries check)
packages/upload-media/src/store/test/retry.ts	New test file with 28 unit tests for retry utilities
packages/upload-media/src/index.ts	Exported ErrorCode, error message functions, and retry-related types
packages/upload-media/README.md	Updated documentation for cancelItem, scheduleRetry, and executeRetry actions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[adamsilverstein]

Review from Claude

I took a pass through the PR after resolving the latest trunk merge conflict. A few substantive issues to flag before this lands, plus a couple of cleanups.

🔴 Error-handling infrastructure is not wired into the code it's meant to handle

The new ErrorCode enum + error-messages.ts + isRetryable getter form a nice vocabulary, but nothing in the package actually produces those codes, and nothing consumes the helpers:

• Actual new UploadError( { code: … } ) sites use string codes like 'HEIC_DECODE_ERROR', 'EMPTY_FILE', 'SIZE_ABOVE_LIMIT', 'MIME_TYPE_NOT_ALLOWED_FOR_USER', 'MIME_TYPE_NOT_SUPPORTED', 'MEDIA_TRANSCODING_ERROR', 'IMAGE_TRANSCODING_ERROR', 'IMAGE_ROTATION_ERROR' — none of which appear in ErrorCode.
• RETRYABLE_CODES contains NETWORK_ERROR, TIMEOUT_ERROR, SERVER_ERROR, VIPS_WORKER_ERROR. Since none of those codes is ever thrown in the current code paths, upload-error.isRetryable effectively always returns false.
• getErrorMessage() / getRetryMessage() / getMaxRetriesExceededMessage() are not imported from anywhere, and ErrorCode / these helpers are not re-exported from packages/upload-media/src/index.ts, so no consumer (this package or plugin code) can use them either.

Suggested direction before merge (pick one):

1. Minimum: migrate all existing throw sites to use ErrorCode values, add ErrorCode to the enum for the remaining legacy codes (HEIC_DECODE_ERROR, EMPTY_FILE, SIZE_ABOVE_LIMIT, MIME_TYPE_NOT_ALLOWED_FOR_USER, MIME_TYPE_NOT_SUPPORTED, MEDIA_TRANSCODING_ERROR), and export ErrorCode + getErrorMessage from index.ts. Also type UploadError.code as ErrorCode | string instead of raw string.
2. Or: drop error-messages.ts and ErrorCode from this PR and land them alongside the UI that consumes them. Otherwise CI will happily ship dead code.

🟡 debug-logger.ts is a compile-time no-op

DEBUG_ENABLED = false is a module-level constant, so measure() always short-circuits in every build. If the goal is to leave hooks in the code for people to turn on during local work, that's fine — but it's worth being explicit:

• Gate it with process.env.NODE_ENV === 'development' or globalThis.SCRIPT_DEBUG, matching the @wordpress/warning pattern. Or
• Expose a setDebugEnabled() / read from a well-known global so it can be flipped without editing the source.

Otherwise a future reader has to grep the file to find the constant and rebuild the package to use it.

🟡 PR description is stale

• README.md is listed as modified, but the diff shows no README change.
• "Retry logic will be handled in a separate PR" — true for auto-retry/scheduling, but the user-initiated retryItem action, retryCount field on QueueItem, and RetryItem reducer/tests are all here (they actually landed in earlier trunk work, but the current description doesn't acknowledge that context).
• getRetryMessage() and getMaxRetriesExceededMessage() shipped with this PR but are scoped to the retry UX that's explicitly not in this PR.

Description should reflect: "adds error-handling vocabulary + logging instrumentation, no consumer wiring yet (follow-up PR)" — or you wire up the consumer and update the description accordingly.

🟡 test-results/.last-run.json is accidentally committed

Already flagged by @andrewserong. Still in the branch:

 test-results/.last-run.json                        |  10 +

Please remove and add test-results/ to .gitignore (currently only test/storybook-playwright/test-results is ignored).

🟡 Unrelated test additions

packages/upload-media/src/store/test/reducer.ts adds tests for PauseQueue, ResumeQueue, CacheBlobUrl, RevokeBlobUrls — which are good tests, but none are touched by this PR. If the intent is "improve reducer coverage while I'm here," that's reasonable to keep, but mention it in the description. Otherwise consider splitting them out so this PR stays focused.

🟡 No CHANGELOG entry

packages/upload-media/CHANGELOG.md has an Unreleased entry from #75257 but nothing for this PR. Add a bullet.

🟢 Nice touches

• The finishUpload idempotency guard in uploadItem (preventing double-dispatch when both onFileChange and onSuccess fire) is a good incidental fix. Worth calling out in the description so it doesn't look like noise.
• @wordpress/warning calls in cancelItem are useful in dev builds; they only emit under SCRIPT_DEBUG, so no prod overhead. 👍
• Sideload measure() instrumentation plays nicely with the new onSuccess(subSize) trunk API after the merge.

Nits

• error-messages.ts: getErrorMessage takes code: string; once the enum is wired up, tightening that to ErrorCode | string will catch typos at callsites.
• The batch-completed warning() fires inside the cancelItem finishing branch, which means a silent cancel of the last item in a batch still logs "Batch completed". If that's intentional, fine, but worth a comment.

[adamsilverstein]

Final sweep + suggested PR description

Merge conflict vs trunk is resolved and pushed (21a8c0c5980) — the sideload change now uses trunk's onSuccess(subSize) callback and keeps the new measure() timing. All 188 upload-media unit tests pass locally.

CodeRabbit (run via coderabbit review --plain --base origin/trunk) returned no findings against this PR's diff.

Remaining items worth addressing before merge

Summarizing from my earlier review for visibility:

1. Wire up ErrorCode or drop it. The enum + isRetryable + error-messages.ts currently have no producers and no consumers. Either migrate existing throw sites to the enum and export from index.ts, or defer this file to the follow-up PR that actually consumes it. Shipping as-is means dead code in npm for one release cycle.
2. Delete test-results/.last-run.json (already flagged by @andrewserong) and consider adding test-results/ to .gitignore. The file is still in the diff.
3. debug-logger.ts gate. DEBUG_ENABLED = false is a compile-time constant — measure() is always a no-op unless someone edits the file. If the goal is "dev-only instrumentation," gate on process.env.NODE_ENV === 'development' or globalThis.SCRIPT_DEBUG (matching @wordpress/warning); otherwise document that this is an opt-in developer tool.
4. Add a CHANGELOG.md entry under the existing ## Unreleased section of packages/upload-media/CHANGELOG.md.
5. Retry helpers — getRetryMessage() / getMaxRetriesExceededMessage() are for the retry UX you've said is out of scope. If the follow-up PR is imminent, leaving them is fine; otherwise consider removing them to keep this PR focused on error classification + logging.