From b3cac753d67993d3657eaa5c38583e48ea01b761 Mon Sep 17 00:00:00 2001
From: Tobias Odendahl <tak@medicuja.com>
Date: Wed, 7 May 2025 02:27:05 +0200
Subject: [PATCH] feat(ui): display the actual error message on unpublish if
 available (#11898)

### What?
If an error occurs while unpublishing a document in the edit view UI,
the toast which shows the error message now displays the actual message
which is sent from the server, if available.

### Why?
Only a generic error message was shown if an unpublish operation failed.
Some errors might be solvable by the user, so that there is value in
showing the actual, actionable error message instead of a generic one.

### How?
The server response is parsed for error message if an unpublish
operation fails and displayed in the toast, instead of the generic error
message.


![image](https://github.com/user-attachments/assets/774d68c6-b36b-4447-93a0-b437845694a9)
---
 packages/ui/src/elements/Status/index.tsx     | 15 ++++++++-
 test/versions/collections/ErrorOnUnpublish.ts | 33 +++++++++++++++++++
 test/versions/config.ts                       |  2 ++
 test/versions/e2e.spec.ts                     | 19 +++++++++++
 test/versions/payload-types.ts                | 27 +++++++++++++++
 test/versions/slugs.ts                        |  1 +
 6 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 test/versions/collections/ErrorOnUnpublish.ts

diff --git a/packages/ui/src/elements/Status/index.tsx b/packages/ui/src/elements/Status/index.tsx
index 0ae421196..6e473e8fc 100644
--- a/packages/ui/src/elements/Status/index.tsx
+++ b/packages/ui/src/elements/Status/index.tsx
@@ -117,7 +117,19 @@ export const Status: React.FC = () => {
           setUnpublishedVersionCount(0)
         }
       } else {
-        toast.error(t('error:unPublishingDocument'))
+        try {
+          const json = await res.json()
+          if (json.errors?.[0]?.message) {
+            toast.error(json.errors[0].message)
+          } else if (json.error) {
+            toast.error(json.error)
+          } else {
+            toast.error(t('error:unPublishingDocument'))
+          }
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        } catch (err) {
+          toast.error(t('error:unPublishingDocument'))
+        }
       }
     },
     [
@@ -154,6 +166,7 @@ export const Status: React.FC = () => {
               <Button
                 buttonStyle="none"
                 className={`${baseClass}__action`}
+                id={`action-unpublish`}
                 onClick={() => toggleModal(unPublishModalSlug)}
               >
                 {t('version:unpublish')}
diff --git a/test/versions/collections/ErrorOnUnpublish.ts b/test/versions/collections/ErrorOnUnpublish.ts
new file mode 100644
index 000000000..c357f7d0d
--- /dev/null
+++ b/test/versions/collections/ErrorOnUnpublish.ts
@@ -0,0 +1,33 @@
+import type { CollectionConfig } from 'payload'
+
+import { APIError } from 'payload'
+
+import { errorOnUnpublishSlug } from '../slugs.js'
+
+const ErrorOnUnpublish: CollectionConfig = {
+  slug: errorOnUnpublishSlug,
+  admin: {
+    useAsTitle: 'title',
+  },
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+      required: true,
+    },
+  ],
+  versions: {
+    drafts: true,
+  },
+  hooks: {
+    beforeValidate: [
+      ({ data, originalDoc }) => {
+        if (data?._status === 'draft' && originalDoc?._status === 'published') {
+          throw new APIError('Custom error on unpublish', 400, {}, true)
+        }
+      },
+    ],
+  },
+}
+
+export default ErrorOnUnpublish
diff --git a/test/versions/config.ts b/test/versions/config.ts
index 36fdb7672..64a227f2b 100644
--- a/test/versions/config.ts
+++ b/test/versions/config.ts
@@ -12,6 +12,7 @@ import DisablePublish from './collections/DisablePublish.js'
 import DraftPosts from './collections/Drafts.js'
 import DraftWithMax from './collections/DraftsWithMax.js'
 import DraftsWithValidate from './collections/DraftsWithValidate.js'
+import ErrorOnUnpublish from './collections/ErrorOnUnpublish.js'
 import LocalizedPosts from './collections/Localized.js'
 import { Media } from './collections/Media.js'
 import Posts from './collections/Posts.js'
@@ -42,6 +43,7 @@ export default buildConfigWithDefaults({
     DraftPosts,
     DraftWithMax,
     DraftsWithValidate,
+    ErrorOnUnpublish,
     LocalizedPosts,
     VersionPosts,
     CustomIDs,
diff --git a/test/versions/e2e.spec.ts b/test/versions/e2e.spec.ts
index f22e7fd5e..26c0cbc4c 100644
--- a/test/versions/e2e.spec.ts
+++ b/test/versions/e2e.spec.ts
@@ -60,6 +60,7 @@ import {
   draftWithMaxCollectionSlug,
   draftWithMaxGlobalSlug,
   draftWithValidateCollectionSlug,
+  errorOnUnpublishSlug,
   localizedCollectionSlug,
   localizedGlobalSlug,
   postCollectionSlug,
@@ -86,6 +87,7 @@ describe('Versions', () => {
   let disablePublishURL: AdminUrlUtil
   let customIDURL: AdminUrlUtil
   let postURL: AdminUrlUtil
+  let errorOnUnpublishURL: AdminUrlUtil
   let id: string
 
   beforeAll(async ({ browser }, testInfo) => {
@@ -124,6 +126,7 @@ describe('Versions', () => {
       disablePublishURL = new AdminUrlUtil(serverURL, disablePublishSlug)
       customIDURL = new AdminUrlUtil(serverURL, customIDSlug)
       postURL = new AdminUrlUtil(serverURL, postCollectionSlug)
+      errorOnUnpublishURL = new AdminUrlUtil(serverURL, errorOnUnpublishSlug)
     })
 
     test('collection — has versions tab', async () => {
@@ -579,6 +582,22 @@ describe('Versions', () => {
       await expect(page.locator('#action-save')).not.toBeAttached()
     })
 
+    test('collections — should show custom error message when unpublishing fails', async () => {
+      const publishedDoc = await payload.create({
+        collection: errorOnUnpublishSlug,
+        data: {
+          _status: 'published',
+          title: 'title',
+        },
+      })
+      await page.goto(errorOnUnpublishURL.edit(String(publishedDoc.id)))
+      await page.locator('#action-unpublish').click()
+      await page.locator('[id^="confirm-un-publish-"] #confirm-action').click()
+      await expect(
+        page.locator('.payload-toast-item:has-text("Custom error on unpublish")'),
+      ).toBeVisible()
+    })
+
     test('should show documents title in relationship even if draft document', async () => {
       await payload.create({
         collection: autosaveCollectionSlug,
diff --git a/test/versions/payload-types.ts b/test/versions/payload-types.ts
index c016d1682..4cb7db427 100644
--- a/test/versions/payload-types.ts
+++ b/test/versions/payload-types.ts
@@ -75,6 +75,7 @@ export interface Config {
     'draft-posts': DraftPost;
     'draft-with-max-posts': DraftWithMaxPost;
     'draft-with-validate-posts': DraftWithValidatePost;
+    'error-on-unpublish': ErrorOnUnpublish;
     'localized-posts': LocalizedPost;
     'version-posts': VersionPost;
     'custom-ids': CustomId;
@@ -97,6 +98,7 @@ export interface Config {
     'draft-posts': DraftPostsSelect<false> | DraftPostsSelect<true>;
     'draft-with-max-posts': DraftWithMaxPostsSelect<false> | DraftWithMaxPostsSelect<true>;
     'draft-with-validate-posts': DraftWithValidatePostsSelect<false> | DraftWithValidatePostsSelect<true>;
+    'error-on-unpublish': ErrorOnUnpublishSelect<false> | ErrorOnUnpublishSelect<true>;
     'localized-posts': LocalizedPostsSelect<false> | LocalizedPostsSelect<true>;
     'version-posts': VersionPostsSelect<false> | VersionPostsSelect<true>;
     'custom-ids': CustomIdsSelect<false> | CustomIdsSelect<true>;
@@ -289,6 +291,17 @@ export interface DraftWithValidatePost {
   createdAt: string;
   _status?: ('draft' | 'published') | null;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "error-on-unpublish".
+ */
+export interface ErrorOnUnpublish {
+  id: string;
+  title: string;
+  updatedAt: string;
+  createdAt: string;
+  _status?: ('draft' | 'published') | null;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "localized-posts".
@@ -589,6 +602,10 @@ export interface PayloadLockedDocument {
         relationTo: 'draft-with-validate-posts';
         value: string | DraftWithValidatePost;
       } | null)
+    | ({
+        relationTo: 'error-on-unpublish';
+        value: string | ErrorOnUnpublish;
+      } | null)
     | ({
         relationTo: 'localized-posts';
         value: string | LocalizedPost;
@@ -778,6 +795,16 @@ export interface DraftWithValidatePostsSelect<T extends boolean = true> {
   createdAt?: T;
   _status?: T;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "error-on-unpublish_select".
+ */
+export interface ErrorOnUnpublishSelect<T extends boolean = true> {
+  title?: T;
+  updatedAt?: T;
+  createdAt?: T;
+  _status?: T;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "localized-posts_select".
diff --git a/test/versions/slugs.ts b/test/versions/slugs.ts
index 5807c381b..b930df706 100644
--- a/test/versions/slugs.ts
+++ b/test/versions/slugs.ts
@@ -19,6 +19,7 @@ export const mediaCollectionSlug = 'media'
 export const versionCollectionSlug = 'version-posts'
 
 export const disablePublishSlug = 'disable-publish'
+export const errorOnUnpublishSlug = 'error-on-unpublish'
 
 export const disablePublishGlobalSlug = 'disable-publish-global'