PayloadCMS: Polymorphic Uploads Crash Fix

Hey everyone! If you're using PayloadCMS and have run into a nasty crash involving polymorphic uploads within a block in your Lexical editor, then you've come to the right place. This article breaks down the bug, provides a detailed reproduction guide, and offers potential insights to help you get back on track. We'll dive deep into the issue, walking through the code, and giving you all the info you need to understand and, hopefully, resolve this frustrating problem. So, let's get started, shall we?

The Bug: Polymorphic Uploads and Lexical Editor Woes

Let's cut to the chase, shall we? The main problem stems from how PayloadCMS handles polymorphic uploads when they're nested within blocks inside a Lexical editor. What does this mean? Basically, if you're using a block with an upload field that can reference multiple collections (like 'assets' and 'media'), you might experience a complete crash of the editor when you try to change the selected upload after saving the document. It's a real bummer, I know!

For those who aren't familiar, a polymorphic upload allows you to upload different types of files or link to files stored in different collections. This is a super powerful feature, but in this specific scenario, it's causing some serious trouble. Imagine you've created a block in your Lexical editor, and that block includes an image upload. Initially, everything works fine. You create a new document, add your block, and select an image from your 'assets' collection. No problems. You save the document, and it all looks great. But here's where the pain begins. If you go back to edit the document and try to change the image to one from the 'media' collection (or even a different image within the 'assets' collection), the editor goes haywire. It crashes, and you might lose your work, which is the last thing you want to happen. This bug is not just annoying; it can be a serious setback if you rely on content that utilizes polymorphic uploads in your PayloadCMS projects. It's a core issue that needs attention, and we are here to provide assistance.

Now, let's look at a concrete example to help clarify things. Imagine a block definition that looks something like this:

export const TestBlock: Block = {
 slug: "test-block",
 fields: [
 {
 type: "text",
 name: "title",
 },
 {
 type: "upload",
 name: "image",
 relationTo: ["assets", "media"],
 required: true,
 }
 ],
};

This code defines a block named 'test-block' with a title field and an upload field called 'image'. The relationTo property specifies that the image can be linked to either the 'assets' or 'media' collection. This is a classic setup for a polymorphic upload. When this block is used within a Lexical editor, the potential for the crash becomes evident. When you try to change the image after saving, the editor can become unstable.

This behavior significantly impacts the usability of the rich text editor if your content strategy requires such flexibility. This bug isn't a minor inconvenience; it's a roadblock to seamless content management. Understanding the core issue is the first step towards finding a solution or workaround.

Code Reproduction: Step-by-Step Guide

Alright, so you've experienced the crash, or maybe you just want to see it in action. Either way, here's how you can reproduce the bug yourself. Follow these steps carefully, and you'll be able to see the problem firsthand and understand the environment in which it occurs. This is more than just a walkthrough. This is your chance to get hands-on and experience the bug firsthand.

Cloning the Repository and Setting Up

First things first, you'll need the code. Clone the repository that has the bug using the following command:

git clone [repository link]

This command will create a local copy of the project on your machine. Once the cloning is complete, navigate into the project directory using your terminal or command prompt. Now, before you run the code, you'll want to install the project dependencies. This step ensures that all the necessary packages and libraries are available. Execute the following command in the project's root directory:

pnpm i

This command installs all the dependencies listed in the package.json file. It might take a few minutes, depending on your internet speed and the number of dependencies. Take a coffee break.

Running the Development Server

With all the dependencies installed, the next step is to start the development server. This allows you to run the application locally and interact with it in your browser. Use the command below to start the PayloadCMS server in development mode:

pnpm dev

This command will start the development server. Once the server is up and running, it typically provides a URL (like http://localhost:3000) where you can access the application. Note this URL, as you will need it shortly.

Accessing the Application

Next, you'll want to access the application through your web browser. Open your web browser and navigate to http://localhost:3000 or whatever address was provided when the development server started. This will take you to the PayloadCMS admin panel, where you can manage your content and trigger the bug. If this is your first time using this application, you might need to set up an admin user and log in.

Seeding the Test Database

To make sure that the application works, you will need to seed the test database. This step populates the database with some initial data. This data is critical because the bug relies on certain configurations within the database, such as the collections 'assets' and 'media'. Ensure that your database has the appropriate setup. With the development server running, you can seed the database.

pnpm run seed

This command will run a script that creates all necessary collections and populates your database with example data, which is essential for reproducing the issue. Follow the instructions to create all the necessary things.

Uploading Images

In order to reproduce the bug, you will need to upload some images into the 'Assets' collection. To do this, go to the 'Assets' collection in the admin panel and upload a few images. These images will be the ones that you will later use in your test blocks and try to replace.

Creating a New Test Document

Next, go to the 'Test' collection (if it doesn't exist, create it) and create a new document. Add a few TestBlocks to this document. Link the images you just uploaded from the 'Assets' collection to these blocks. This step is about setting up the basic structure of your test document, including the polymorphic upload setup.

Saving the Document

After adding the test blocks and linking your images, save the document. This saves the document for the first time with everything you set up, which includes the image uploads, which is a critical step for reproducing the bug.

Editing the Document

Once the document is saved, go back to edit it. This step is where you'll trigger the bug. Now, try to change the images within the blocks to an image from a different collection (or even a different image within the same collection). When you attempt to change the upload in the block to an image from the 'media' collection, for example, the editor should crash. The editor's instability at this point confirms the presence of the polymorphic upload bug. This is the moment where the editor crashes.

This step-by-step guide is your blueprint for understanding and experiencing the crash. By following these steps, you'll not only see the bug in action but also gain a deeper understanding of its cause.

Affected Area: Rich Text and Core Plugins

Okay, so where exactly does this bug reside in the PayloadCMS ecosystem? According to the report, the primary areas affected are the richtext-lexical plugin and the core functionality of PayloadCMS itself. This means that the issue isn't isolated to a single component; it's a cross-cutting problem that touches both the rich text editing capabilities and the fundamental core of the system.

The richtext-lexical plugin is responsible for the rich text editor's features, including the handling of blocks and their content. The fact that the crash occurs when manipulating polymorphic uploads within the rich text editor's blocks suggests that the problem lies within this plugin's interaction with the core system. The core is responsible for handling database interactions, the management of uploads, and how data is stored and retrieved. The integration between these two areas is where the bug manifests. When a polymorphic upload is part of the blocks and is being handled, things go wrong.

Knowing which areas are affected can help guide efforts to find a solution or workaround. You know that the issue is within the rich text editor (Lexical) and how it handles polymorphic uploads linked to the core. This is where your focus should be.

Environment Information: Key Dependencies

Understanding your environment is critical when diagnosing any software issue. The environment information provided in the report gives us a clear picture of the specific setup where the bug occurs. This includes details about the versions of libraries and the operating system in use. Let's break down the important pieces.

The report lists the following key dependencies:

• Node: Version 24.8.0
• PayloadCMS: Version 3.63.0
• Next.js: Version 15.4.7
• Database: MongoDB
• React: Version 19.1.0
• Operating System: Windows 11 Pro

Knowing the precise versions of these components is crucial. For instance, the PayloadCMS version (3.63.0) tells you which features and potential bug fixes are in play. The React version (19.1.0) and Next.js (15.4.7) versions provide insights into the frontend framework and its capabilities. The database details specify the database system being used, which may influence how uploads and data are managed. The OS details help determine compatibility issues and possible environmental conflicts. It's crucial to ensure that your environment matches the provided details as closely as possible when attempting to reproduce or resolve the issue.

Conclusion and Next Steps

So, there you have it, folks! We've taken a deep dive into the polymorphic upload bug in PayloadCMS. We've talked about what the bug is, how to reproduce it, and which parts of the system are affected. It's a tricky one, no doubt, but now you have a better understanding of the issue. The ability to reproduce and understand the bug gives you a significant advantage in dealing with it.

Now, you might be asking,