Unique property not respected on updates with draft and validate enabled

[tobidemski]

Describe the Bug

Hello,

I tried to use the unique: true property on a field. It works if a new document is created but not if I try to update a document with the same value of a different document.

Both documents where still in draft mode.

You can use the referenced repo and enable drafts like this

  versions: {
    drafts: {
      validate: true,
    },
    maxPerDoc: 1,
  },

Link to the code that reproduces this issue

https://github.com/tobidemski/payload-uniquefield-errormessage

Reproduction Steps

1. use Payload with sqlite
2. Create a page document with any value. Example "/" for the page field and save it.
3. Create a second document with the same value "/" and try to save. --> Error is shown
4. Set the page field value for the second document to "test" and save --> succesful
5. Set the page field value for the secon document to "/" and save --> successful

Which area(s) are affected? (Select all that apply)

area: docs

Environment Info

Binaries:
  Node: 18.20.8
  npm: N/A
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  payload: 3.39.1
  next: 15.3.2
  @payloadcms/db-postgres: 3.39.1
  @payloadcms/email-nodemailer: 3.39.1
  @payloadcms/graphql: 3.39.1
  @payloadcms/next/utilities: 3.39.1
  @payloadcms/payload-cloud: 3.39.1
  @payloadcms/richtext-lexical: 3.39.1
  @payloadcms/translations: 3.39.1
  @payloadcms/ui/shared: 3.39.1
  react: 19.0.0
  react-dom: 19.0.0
Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 10 Pro
  Available memory (MB): 32510
  Available CPU cores: 16

[GermanJablo]

It works fine for me. I'm trying it with your repository.

Screen.Recording.2025-06-03.at.5.23.29.PM.mov

This is my payload info. Maybe you'd like to try updating payload and node?

Binaries:
  Node: 22.11.0
  npm: 10.9.0
  Yarn: N/A
  pnpm: 10.11.0
Relevant Packages:
  payload: 3.40.0
  next: 15.3.0
  @payloadcms/email-nodemailer: 3.40.0
  @payloadcms/graphql: 3.40.0
  @payloadcms/next/utilities: 3.40.0
  @payloadcms/payload-cloud: 3.40.0
  @payloadcms/richtext-lexical: 3.40.0
  @payloadcms/translations: 3.40.0
  @payloadcms/ui/shared: 3.40.0
  react: 19.1.0
  react-dom: 19.1.0
Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.4.0: Wed Feb 21 21:44:54 PST 2024; root:xnu-10063.101.15~2/RELEASE_ARM64_T6030
  Available memory (MB): 18432
  Available CPU cores: 12

[tobidemski]

Hey @GermanJablo,

thanks for taking a look into this. I can see there is a difference between your and my approach.
You are pressing directly the Publish button and I only pressed the "Save Draft" button.
I tested your approach and I have the same result as you have.

I would have expected that I already get an error message if the same unique value is already presented in one of the other documents even if my new document is saved in a draft mode.

Following scenarios:
Both in draft:
NEW First document contains unique value "/" --> Save Draft (not published) --> OK <-- EXPECTED
NEW Second document contains unique value "/" --> Save Draft (not published) --> Error message <-- EXPECTED

One in draft one published:
NEW First document contains unique value "/" --> Published --> OK
NEW Second document contains unique value "/" --> Save Draft (not published) --> Error message <-- EXPECTED

• Change second document unique value to "test" --> Save Draft (not published) --> OK

UPDATED Second document contains unique value "/" --> Save Draft (not published) --> OK <--- NOT EXPECTED

Conclusion:
Its possible to reach a state where two documents can have the same unique value even tho only one document can be published. I would expect only one document in the whole collection can have a unique value regardless of the publishing state (draft/published)

[GermanJablo]

I see @tobidemski, thanks for clarifying!

I understand how this can be confusing, but there's some logic behind the current behavior, so let me explain.

The TLDR is: "The save draft button never modifies the main table unless the document is being created for the first time."

When you enable versioning, and therefore the same applies to drafts, payload creates a new _pages_version table that is different from the pages table. The unique: true property applies only to the pages table.

Once you complete step 4 of your Reproduction Steps, the second document is identical in both tables (pages = "test"). But in step 5, you're only modifying the document in the _pages_version table.

This makes sense because you don't want the save draft to modify the published document. We could make the exception that save draft modifies the document in the main table ONLY if it has never been published, but the logic seems arbitrarily complex and slow, and it would be a breaking change.

Does this make more sense now?

[tobidemski]

Thanks for the explanation @GermanJablo and I understand the current behaviour!

But as an end user it is really confusing when you can create multiple documents with the same unique value after you saved each document with a different value.
Is there a reason why the unique: true property is only applied to the pages table instead of the following:

• Save draft --> unique: true applies to _pages_version table
• Publish changes --> unique: true applies to pages table
  This would prevent that you could have multiple draft documents with the same unique field value and while publishing only one document can be in the pages table.

When creating a new document, “error handling” behaves as expected and returns an error if a document already exists, but this is not the case when updating. I would assume that validation should always be the same for an end user, regardless of whether they are “saving a draft” or “publishing.”

[GermanJablo]

unique: true applies to _pages_version table
[...] This would prevent that you could have multiple draft documents with the same unique field value [...]

We've considered those options and others. But it wouldn't be a good idea. Tables like _pages_versions are just that: a version history. You don't want to be blocked from saving version 1000 because version 1 happened to have the same value in some field. The value is expected to be unique compared to other documents, not to previous versions of the same document.

When creating a new document, “error handling” behaves as expected and returns an error if a document already exists, but this is not the case when updating. I would assume that validation should always be the same for an end user, regardless of whether they are “saving a draft” or “publishing.”

The reason for this is what I explained in my previous comment:

"The save draft button never modifies the main table unless the document is being created for the first time."
[...]
This makes sense because you don't want the save draft to modify the published document. We could make the exception that save draft modifies the document in the main table ONLY if it has never been published, but the logic seems arbitrarily complex and slow, and it would be a breaking change.

I hope this makes sense to you now. If it doesn't yet, I suggest opening a feature request on Github Discussions that allows you to restrict unique values ​​between versions of a document. Again, I can't think of a use case, but we can look into it if we find situations where this might be useful.

Or, you could create a custom hook that achieves this behavior. It shouldn't be too difficult.

I'm closing this issue but I'll be listening for any additional comments you may have.

Thanks!

[github-actions]

This issue has been automatically locked.
Please open a new issue if this issue persists with any additional detail.