Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: adds Reserved Field Names section to migration guide #11308

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: adds Reserved Field Names section to migration guide #11308

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8545173
docs: adds reserved field names section
PatrikKozak Feb 20, 2025
cfe01fa
Merge branch 'main' of github.com:payloadcms/payload into docs/reserv…
PatrikKozak Feb 20, 2025
244b0e4
chore: updates reserved field name section again
PatrikKozak Feb 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions docs/migration-guide/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1104,6 +1104,57 @@ plugins: [

If you have custom features for `@payloadcms/richtext-lexical` you will need to migrate your code to the new API. Read more about the new API in the [documentation](https://payloadcms.com/docs/rich-text/building-custom-features).

## Reserved Field names

Payload reserves certain field names for internal use. Using any of the following names in your collections or globals will result in those fields being sanitized from the config, which can cause deployment errors. Ensure that any conflicting fields are renamed before migrating.

### General Reserved Names

- `file`
- `_id` (MongoDB only)
- `__v` (MongoDB only)

**Important Note**: It is recommended to avoid using field names with an underscore (`_`) prefix unless explicitly required by a plugin. Payload uses this prefix for internal columns, which can lead to conflicts in certain SQL conditions. The following are examples of reserved internal columns (this list is not exhaustive and other internal fields may also apply):

- `_order`
- `_path`
- `_uuid`
- `_parent_id`
- `_locale`

### Auth-Related Reserved Names

These are restricted if your collection uses `auth`: true and does not have `disableAuthStrategy: true`:
- `salt`
- `hash`
- `apiKey` (when `auth.useAPIKey: true` is enabled)
- `useAPIKey` (when `auth.useAPIKey: true` is enabled)
- `resetPasswordToken`
- `resetPasswordExpiration`
- `password`
- `email`
- `username`

### Upload-Related Reserved Names

These apply if your collection has `upload: true` configured:

- `filename`
- `mimetype`
- `filesize`
- `width`
- `height`
- `focalX`
- `focalY`
- `url`
- `thumbnailURL`

If `imageSizes` is configured, the following are also reserved:

- `sizes`

If any of these names are found in your collection / global fields, update them before migrating to avoid unexpected issues.

## Upgrade from previous beta

Reference this [community-made site](https://payload-releases-filter.vercel.app/?version=3&from=152429656&to=188243150&sort=asc&breaking=on). Set your version, sort by oldest first, enable breaking changes only.
Expand Down