Payload CMS: Cannot Create User With Custom BasePath In Dev

by Alex Johnson 60 views

Introduction

This article addresses a specific bug encountered in Payload CMS where creating the first user with a custom basePath fails in development mode. We'll delve into the details of the issue, the steps to reproduce it, and the environment in which it occurs. This comprehensive guide aims to provide clarity and potential solutions for developers facing this problem. When working with Payload CMS, encountering issues during development can be frustrating. One such issue arises when attempting to create the first user with a custom basePath set in development mode. This problem leads to a 404 error because the system tries to send a POST request to the default API route instead of the custom route defined by basePath. Understanding this issue and how to reproduce it is the first step toward finding a solution.

Describe the Bug

The core of the bug lies in how Payload CMS handles the first-register API route in development versus production environments. When a custom basePath is set (e.g., "/payload"), the application should direct API requests to the corresponding route (e.g., http://localhost:3000/payload/api/users/first-register). However, in development mode, Payload CMS incorrectly sends the POST request to the default route (http://localhost:3000/api/users/first-register), resulting in a 404 error. This discrepancy between development and production environments can be particularly perplexing. In essence, the system fails to recognize the custom basePath during the initial user creation process in the development environment. This means that the application's routing mechanism, which should direct the request to the correct endpoint, is not functioning as expected. This misdirection causes the request to land on an incorrect URL, hence the 404 error. The Payload CMS configuration, specifically the basePath setting, plays a crucial role in how API routes are resolved. When this setting is not correctly applied in development, it leads to these routing errors. Furthermore, this issue highlights the differences in how Payload CMS handles routing in development versus production, which is a critical factor to consider during debugging. This bug affects the initial setup process, preventing developers from quickly starting with a customized Payload CMS instance. Understanding the nuances of how basePath is handled is essential for anyone looking to deploy Payload CMS with custom configurations.

Reproduction Steps

To reproduce this bug, follow these steps:

  1. Checkout the reproduction repository: Begin by cloning the provided repository, which is specifically set up to demonstrate this issue. This ensures that you have the correct codebase and configuration to replicate the bug.
  2. Install dependencies: Navigate into the cloned repository and run npm install to install all necessary dependencies. This step is crucial to ensure that all the project's requirements are met.
  3. Run in development mode: Execute the command npm run dev to start the application in development mode. This is where the bug manifests itself.
  4. Access the admin interface: Open a web browser and navigate to http://localhost:3000/payload/admin. Note the inclusion of /payload in the URL, which corresponds to the custom basePath.
  5. Fill the first user form: On the admin interface, you will be presented with the "Create first user" form. Fill in the required details.
  6. Click the Create button: After filling in the form, click the "Create" button to submit the user creation request.
  7. Observe the 404 error: Upon clicking the create button, the application will attempt to send a POST request to the incorrect URL (http://localhost:3000/api/users/first-register) instead of the correct one (http://localhost:3000/payload/api/users/first-register). This will result in a 404 error, confirming the bug. Following these steps precisely will allow you to reliably reproduce the issue in your local environment. The reproduction steps are designed to isolate the problem and confirm that it is consistently reproducible under the specified conditions. This systematic approach is essential for effective debugging and issue resolution. By reproducing the bug, developers can gain a clearer understanding of its behavior and potential causes. These steps ensure that the environment and configuration match the conditions under which the bug was originally reported, making the debugging process more efficient.

Link to the Code that Reproduces this Issue

The code repository that reproduces this issue can be found at https://github.com/jefferyto/payload-basepath-first-register. This repository contains a minimal setup that demonstrates the bug, allowing developers to easily reproduce and investigate the issue. Accessing the reproduction repository is a critical step in understanding and addressing the problem. The repository provides a self-contained example that eliminates external factors, making it easier to focus on the core issue. By examining the code, developers can gain insights into how the basePath is configured and how the API requests are being routed. The repository serves as a shared resource for the community, enabling collaboration and collective problem-solving. It allows others to independently verify the bug and contribute potential fixes. Having a reproducible example is invaluable for both the developers of Payload CMS and the community, as it accelerates the process of identifying and resolving issues.

Affected Areas

This bug primarily affects the core functionality of Payload CMS, specifically the user creation process. Since creating the first user is a fundamental step in setting up a new instance, this issue can be a significant blocker for developers. The affected area is the core of Payload CMS, which means that the bug is not limited to a specific plugin or feature but rather impacts the essential operations of the system. The user creation process is critical for accessing and managing the CMS, so any issues in this area can have far-reaching consequences. Specifically, the first-register endpoint, which is responsible for handling the initial user creation, is directly affected. This endpoint's failure to function correctly in development mode hinders the smooth setup of Payload CMS environments. The impact extends to developers who rely on a consistent experience between development and production environments. A bug that only appears in development can lead to confusion and wasted time as developers try to debug issues that do not manifest in production. Addressing this bug in the core ensures a more reliable and predictable development experience for all Payload CMS users.

Environment Information

The bug was observed in the following environment:

Binaries:
  Node: 22.21.1
  npm: 11.6.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  payload: 3.64.0
  next: 15.4.7
  @payloadcms/db-sqlite: 3.64.0
  @payloadcms/drizzle: 3.64.0
  @payloadcms/graphql: 3.64.0
  @payloadcms/next/utilities: 3.64.0
  @payloadcms/richtext-lexical: 3.64.0
  @payloadcms/translations: 3.64.0
  @payloadcms/ui/shared: 3.64.0
  react: 19.1.0
  react-dom: 19.1.0
Operating System:
  Platform: linux
  Arch: x64
  Version: #36-Ubuntu SMP PREEMPT_DYNAMIC Sat Oct 11 02:18:29 UTC 2025
  Available memory (MB): 7225
  Available CPU cores: 4

This environment information is crucial for understanding the context in which the bug was encountered. It includes details about the versions of Node.js, npm, Payload CMS, Next.js, and other relevant packages. Knowing the environment in which the bug occurs helps to narrow down potential causes and identify compatibility issues. The specific versions of Payload CMS and its dependencies are particularly important, as bugs may be introduced or fixed in certain releases. The operating system and hardware information can also be relevant, as some bugs may be platform-specific. This detailed environment information allows developers to reproduce the bug in a similar setup, which is essential for effective debugging. The versions of the various packages and tools involved provide a snapshot of the software ecosystem at the time the bug was reported, helping to identify any potential version-related conflicts.

Conclusion

The issue of failing to create the first user with a custom basePath in Payload CMS development mode is a significant hurdle for developers. This article has outlined the bug, provided clear reproduction steps, and detailed the affected environment. By understanding the problem and its context, developers can better troubleshoot and contribute to finding a solution. This issue highlights the importance of thorough testing across different environments to ensure a seamless user experience. For further information and resources on Payload CMS, visit the Payload CMS Official Documentation. This external link provides access to comprehensive guides, API references, and other valuable information for working with Payload CMS. By consulting the official documentation, developers can gain a deeper understanding of the system and its capabilities. This resource is essential for both beginners and experienced users of Payload CMS.