Spree.metafields is deprecated and will be removed in Spree

Error message

Spree.metafields is deprecated and will be removed in Spree 6.1. Use Spree.custom_fields instead.

What it means

Spree 6.0 renamed Metafields to Custom Fields, and the registry accessor Spree.metafields (which reads Rails.application.config.spree.custom_fields) became Spree.custom_fields. The old reader survives for one release: it warns, then returns the same registry. Removed in Spree 6.1, after which calls raise NoMethodError.

Source

Thrown at spree/core/lib/spree/core.rb:535

  # @return [Spree::SetupTasks]
  def self.store_setup_tasks
    @store_setup_tasks ||= Spree::SetupTasks.new
  end

  def self.translatable_resources
    Rails.application.config.spree.translatable_resources
  end

  def self.translatable_resources=(value)
    Rails.application.config.spree.translatable_resources = value
  end

  def self.custom_fields
    Rails.application.config.spree.custom_fields
  end

  def self.metafields
    Spree::Deprecation.warn('Spree.metafields is deprecated and will be removed in Spree 6.1. Use Spree.custom_fields instead.') if defined?(Spree::Deprecation)
    custom_fields
  end

  def self.integrations
    Rails.application.config.spree.integrations
  end

  def self.integrations=(value)
    Rails.application.config.spree.integrations = value
  end

  # Registry mapping a numbered resource to the generator that produces its
  # document numbers. With no entry, the store's `document_number_format`
  # preference picks between the sequential and random strategies.
  #
  # @return [Spree::NumberGenerators::Registry]
  # @example Custom order numbers
  #   Spree.number_generators[:order] = 'MyApp::BranchOrderNumbers'

View on GitHub (pinned to 06bf66a868)

Solutions

Use Spree.custom_fields for reads and registration
Sweep: grep -rn 'Spree.metafields' config lib app
Upgrade extensions that register definitions through the old accessor
Run the suite with deprecations raised so stale registry access fails loudly

Example fix

# before
Spree.metafields << MyExtension::FieldDefinition

# after
Spree.custom_fields << MyExtension::FieldDefinition

Defensive patterns

Strategy: validation

Validate before calling

grep -rn 'Spree\.metafields' config lib app && echo 'PORT NEEDED' || echo 'clean'

Type guard

Spree.respond_to?(:custom_fields)  # true on Spree 6

Prevention

Register custom-field definitions through Spree.custom_fields in extension initializers
Feature-detect in gems supporting both 5.x and 6.0: Spree.respond_to?(:custom_fields) ? Spree.custom_fields : Spree.metafields
Raise deprecations in test

When it happens

Trigger: Calling Spree.metafields to register or enumerate custom field definitions - typically in extension initializers (Spree.metafields << MyDefinition) or host-app config that adds resource types to the registry.

Common situations: Extensions written against the 5.x metafields vocabulary (docs/plans/5.4-6.0-custom-fields-rename.md); host apps registering custom field definitions; code enumerating registrable resources for admin UIs.

Related errors

AI-assisted analysis of spree/spree@06bf66a868 (2026-08-21). Data as JSON: /api/errors/ef4708d76a973359. Report an issue: GitHub.