🐛 Improved upload error messages in the editor

[mike182uk]

ref https://linear.app/ghost/issue/ONC-1847/cant-upload-files

Context

This contributes to ONC-1847 (file uploads in the editor failing with no useful feedback). It does not close the issue on its own — see "Scope" below.

Problem

When an upload in the editor failed (e.g. a file exceeding the plan's upload-size limit), the error surfaced to the user was unhelpful:

• The card showed a generic "Host Limit error, cannot upload image." instead of the actionable message (e.g. "Your plan supports uploads up to X. Please upgrade to upload larger files.").
• Repeated failed uploads stacked duplicate error messages.

Fix

apps/admin-x-framework/src/hooks/use-koenig-file-upload.ts:

1. Wrong message shown. The API (@tryghost/mw-error-handler) wraps some errors with a generic message and puts the specific, user-facing text in context. The hook surfaced message. It now prefers context, falling back to message — matching the existing getErrorMessage convention used elsewhere in the admin.

2. Duplicate errors. The hook appended each failure to the existing errors array, so retrying a failing upload accumulated duplicates. It now clears errors at the start of each attempt and replaces rather than appends on failure.

Tests

Added unit tests covering both behaviours (prefer context; no accumulation across retries). All 15 hook tests pass.

Scope

The actual ONC-1847 symptom — the file card showing no error at all when an upload fails — is caused by the file card's error rendering in @tryghost/koenig-lexical and is fixed there in TryGhost/Koenig#1994.

This PR is a prerequisite: it fixes the error text (visible today on the image card) and the duplicate-message behaviour. Once Koenig#1994 is published and bumped in Ghost, the file card will show the correct, non-duplicated message and ONC-1847 is fully resolved.

Before

CleanShot.2026-06-18.at.17.14.26.mp4

After

CleanShot.2026-06-18.at.17.24.26.mp4

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c67953df-8fe1-43fc-8c79-07b1add62071

📥 Commits

Reviewing files that changed from the base of the PR and between 32d4352 and 05cb7ff.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (3)

• apps/admin-x-framework/src/hooks/use-koenig-file-upload.ts
• apps/admin-x-framework/test/unit/hooks/use-koenig-file-upload.test.ts
• pnpm-workspace.yaml

✅ Files skipped from review due to trivial changes (1)

• pnpm-workspace.yaml

🚧 Files skipped from review as they are similar to previous changes (2)

• apps/admin-x-framework/test/unit/hooks/use-koenig-file-upload.test.ts
• apps/admin-x-framework/src/hooks/use-koenig-file-upload.ts

---

Walkthrough

The use-koenig-file-upload hook's error handling is updated in two areas. In uploadFile, the catch block now uses getStringAtPath to extract both context and message from API error responses, building the thrown errorResult with context preferred over message for the user-facing message field. In upload, errors are cleared with setErrors([]) before each attempt begins, and the catch block replaces the errors array with a single-entry array instead of appending to it. Two new unit tests are added: one using a new hostLimitUploadResponse mock to verify context is surfaced over message, and another to verify errors do not accumulate across repeated failed upload attempts. The @tryghost/koenig-lexical dependency version is also bumped from 1.8.2 to 1.8.3 in the workspace catalog.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: improving error message display for file uploads in the editor, which is the core objective of this PR.
Description check	✅ Passed	The description comprehensively explains the problem, solution, testing approach, and scope with clear references to the issue and related work.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-koenig-upload-error-messages

---

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

[nx-cloud]

🤖 Nx Cloud AI Fix

Ensure the fix-ci command is configured to always run in your CI pipeline to get automatic fixes in future runs. For more information, please see https://nx.dev/ci/features/self-healing-ci

---

View your CI Pipeline Execution ↗ for commit 05cb7ff

Command	Status	Duration	Result
nx run ghost:test:ci:legacy	✅ Succeeded	1m 50s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-23 07:00:26 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.87%. Comparing base (4620a3b) to head (05cb7ff).
⚠️ Report is 87 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #28723      +/-   ##
==========================================
+ Coverage   73.81%   73.87%   +0.05%     
==========================================
  Files        1550     1557       +7     
  Lines      133527   134542    +1015     
  Branches    16065    16192     +127     
==========================================
+ Hits        98561    99389     +828     
- Misses      33989    34174     +185     
- Partials      977      979       +2     

Flag	Coverage Δ
admin-tests	55.16% <ø> (+0.10%)	⬆️
e2e-tests	75.97% <ø> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.