Magento Duplicate SKU: Make the Column Actually Unique

catalog_product_entity.sku carries no unique constraint. Two concurrent API creates produce two products with one SKU — every time. This closes both halves.

catalog_product_entity.sku carries an ordinary btree index, not a unique constraint. Uniqueness lives entirely in PHP: the product repository runs an unlocked SELECT for the SKU, treats an empty result as "create", and inserts. Nothing underneath rejects the second row. Two creates for the same SKU that overlap inside that window therefore both succeed — two 200s, two entity ids, one SKU — and on 2.4.8-p5 that reproduced on fourteen of fourteen attempts, through the repository and over REST alike.

Typical impact: the failure mode this prevents is not a duplicate you can see. It is either a SKU that can never be written again — every later update returns "URL key for specified store already exists" — or an orphan product on a live SKU that no SKU-addressed route can reach and no reconciliation counts.

Who it is for

  • Anyone importing products over REST from more than one worker, or with retries — a timeout that leaves the first call running and fires a second is the same race from a single-threaded importer.
  • Teams whose imports have started failing on URL key for specified store already exists for a SKU whose name never changed. That message names the slug and means the duplicate.
  • Anyone running SELECT sku, COUNT() FROM catalog_product_entity GROUP BY sku HAVING COUNT() > 1 and finding rows.

Who should skip it

  • Adobe Commerce with Content Staging. The schema half must not be installed there: staging replaces the table’s primary key with row_id and legitimately stores several rows per SKU, scoped by created_in / updated_in. That constraint is exactly why the fix has never shipped upstream.
  • Installs that already contain duplicates — setup:upgrade refuses to apply the constraint until they are cleaned up, which is deliberate.
  • Single-writer imports with no retry and no parallelism, where the window is never open.
  • Installs on 2.4.9, or carrying Adobe’s ACSD-64118 patch, that only ever want the lock. Adobe’s own now covers the common case; what is left is the constraint and one edge the patch does not reach, both below.

What it does

Two independent layers, and both matter:

  • A unique constraint on the SKU column, so the database rejects the second row rather than trusting the application to have checked.
  • A per-SKU lock across the repository save, using the framework’s own LockManagerInterface, so the get-or-create window is serialised rather than raced. The second call becomes an update instead of an error. The lock name is the SKU lowercased and trimmed before hashing, which matters more than it sounds — see Upstream.

Measured on 2.4.8-p5 with two parallel POST /V1/products carrying one SKU:

InstalledResult
stock Magento200 + 200, two rows
the constraint alone200 + 400 Unique constraint violation found, one row
constraint and lock200 + 200 with the same id, one row — the second call is an update

The lock is the half that leads to a clean outcome rather than merely a safe one: a correct concurrent importer sees an upsert, not a failure it has to interpret.

Upstream: Adobe shipped half of this

Adobe has its own lock now. ACSD-64118, in Quality Patches Tool 1.1.65, adds Magento\Catalog\Model\ProductMutex and an aroundSave plugin on the product repository — the same shape as the plugin here, one framework lock per SKU held across the save. It is in 2.4.9 core, and the patch covers >=2.4.4 <2.4.7, >=2.4.7 <2.4.7-p10 and >=2.4.8 <2.4.8-p5 through three files under one ticket.

Three things outlive it.

The database still has no opinion. 2.4.9’s catalog_product_entity carries the same non-unique btree index it always did. Adobe closed the window; nothing underneath rejects a duplicate row if anything ever gets past it. That is the half PR #33191 proposed and the staging objection blocked, and it is still unshipped.

Adobe’s lock name is the raw SKU. ProductMutex locks on product_mutex_ plus the SKU exactly as sent. The sku column is utf8mb4_general_ci, so abc-1 and ABC-1 are one row — but GET_LOCK compares names case- and byte-sensitively, so they are two locks. Measured on MariaDB 10.6: while a lowercase lock is held, IS_USED_LOCK on the uppercase spelling, or on the same name with a trailing space, returns NULL. Two concurrent creates that disagree only in case or whitespace therefore pass Adobe’s mutex side by side and still produce two rows. This module hashes the SKU lowercased and trimmed first — the same normalization ProductRepository::prepareSku() already applies — so those spellings take one lock.

And one version has neither. On 2.4.8-p5 the patch declares itself out of range and magento/module-catalog 104.0.8-p5 contains no ProductMutex at all. Which is exactly where the fourteen duplicates above were measured. ./vendor/bin/magento-patches status | grep 64118 is the question worth asking before assuming an install is covered.

Issue #31125 has been open and confirmed since December 2020. PR #41181 proposed the same lock in core, independently and before ACSD-64118 surfaced; what is left worth landing there is the normalization Adobe’s version does not do.

Installation

composer require brocode/module-unique-sku
bin/magento module:enable BroCode_UniqueSku
bin/magento setup:upgrade
bin/magento setup:di:compile

Reconcile first. If the catalog already holds duplicates, the schema step will refuse — clean them with the grouping query above, checking which entity owns the url_rewrite row before deleting anything, because delete-by-SKU removes the lowest id.

Compatibility

Magento 2 Open Source, PHP 8.1 through 8.5. Verified on 2.4.8-p5. On 2.4.9, and on anything carrying ACSD-64118, both plugins coexist: Adobe’s wraps this one, each save takes two named locks in a fixed order, and neither can deadlock the other. Not for Adobe Commerce with Content Staging — see Who Skip; install the lock half only if you need protection there.

FAQ

Does the lock slow down imports?

It serialises saves of the same SKU, which a correct importer never does concurrently anyway. Different SKUs are unaffected.

Why not just partition the feed by SKU instead?

Do that as well — hash the SKU to a worker so one SKU is only ever held by one process. It is free and it removes most of the exposure. The module covers what partitioning cannot: retries, and any second writer you did not know about.

Adobe patched this. Do I still need the module?

For the lock alone on 2.4.9, or on a version ACSD-64118 applies to: mostly no, and that is fine. What is left is the unique constraint, which Adobe has never shipped, and SKUs whose spelling varies in case or whitespace between two concurrent writers, which Adobe’s lock does not catch. Both plugins can run together — Adobe’s wraps this one, so the requests its lock lets through side by side meet on the normalized lock inside it — at the cost of one extra lock round trip per save.

Does async/bulk avoid the race?

No. It is the same repository behind several consumers, and duplicates have been reported from that path specifically. It also adds a duplication route of its own: the content hash in the queued response is not an idempotency key, so a re-sent batch is accepted again and executed again — measured on 2.4.8-p5 and written up in Magento Async Bulk API: What the 202 Doesn’t Tell You.

Related reading

Ask a module question or suggest improvements

Tell us your use case and the module context. Spam protection is handled by ALTCHA.




More Projects