●Change8

Migrating to Payload CMS v3.71.0

Version v3.71.0 introduces 1 breaking change. This guide details how to update your code.

Released: 1/13/2026

1
Breaking Changes
4
Migration Steps
16
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

Job Queue Concurrency ConfigurationStatus Component (Admin UI)workflowstasksbulkOperations.singleTransactionDateTimeFormat validationJobCancelledErrortypescript.strictDraftTypesValidationError (Drizzle)plugin-ecommerce hooks (onLogin, onLogout, clearSession, mergeCart)useCart.refreshCartplugin-import-exportMCP find resource toolMCP global update toolsGenerateURL type (plugin-nested-docs)GenerateLabel type (plugin-nested-docs)

Breaking Changes

●Issue #1

{"fix":"Explicitly set `enableConcurrencyControl: true` in the `jobs` configuration if you rely on concurrency controls.","breaking_change":"The default behavior for exclusive concurrency controls is changing. In v3.71.0, `enableConcurrencyControl` defaults to `false` for jobs, but it will default to `true` in v4.0. Users enabling exclusive concurrency controls should explicitly set `enableConcurrencyControl: true` in their configuration to ensure future compatibility."}

✓Solution

Explicitly set `enableConcurrencyControl: true` in the `jobs` configuration if you rely on concurrency controls.

Migration Steps

  1. 1
    If using job concurrency controls and aiming for v4.0 compatibility, explicitly set `enableConcurrencyControl: true` in your `jobs` configuration.
  2. 2
    If you need to stop a running job without retrying, throw `JobCancelledError` from within the workflow or task handler.
  3. 3
    If using draft queries and requiring strict type safety for required fields, enable `typescript.strictDraftTypes: true`.
  4. 4
    If using plugin-ecommerce, be aware that cart logic has moved server-side, utilizing new hooks and API endpoints.

Release Summary

This release introduces significant enhancements to job queue concurrency, including superseding and exclusive controls, alongside major updates to the e-commerce plugin's cart logic moving to the server. It also adds several developer experience improvements like stricter TypeScript draft typing and better validation error context.

Need More Details?

View the full release notes and all changes for Payload CMS v3.71.0.

View Full Changelog