What causes "Template.register_tag" in Shopify/liquid?

Template.register_tag

Error message

Template.register_tag

What it means

Liquid::Template.register_tag is deprecated in favor of Environment#register_tag; the shim registers the tag on Environment.default and emits a deprecation warning. Tag registries became per-environment so different apps/environments can have different tag sets.

Solutions

Call Liquid::Environment.default.register_tag(name, klass)
Or register the tag on a custom Environment and pass that environment when parsing

Example fix

// before
Liquid::Template.register_tag('render_snippet', SnippetTag)
// after
Liquid::Environment.default.register_tag('render_snippet', SnippetTag)

Defensive patterns

Strategy: validation

Validate before calling

Liquid::Environment.default.register_tag(name, klass)

Prevention

Register custom tags on Environment (default or per-app) instead of Template
When authoring gems, accept an Environment argument rather than mutating globals
Run test suites with deprecation warnings promoted to errors

When it happens

Trigger: Calling Liquid::Template.register_tag('name', TagClass) in an initializer, engine, or gem setup code.

Common situations: Rails engines and libraries registering custom Liquid tags at boot; apps upgraded from Liquid 4 where Template was the registry.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

AI-assisted analysis of Shopify/liquid@807d45a6b3 (2026-09-08). Data as JSON: /api/errors/64ab4358b2595e99. Report an issue: GitHub.

Appendix: source

Thrown at lib/liquid/template.rb:61

      def default_exception_renderer
        Environment.default.exception_renderer
      end

      def file_system=(file_system)
        Deprecations.warn("Template.file_system=", "Environment#file_system=")
        Environment.default.file_system = file_system
      end

      def file_system
        Environment.default.file_system
      end

      def tags
        Environment.default.tags
      end

      def register_tag(name, klass)
        Deprecations.warn("Template.register_tag", "Environment#register_tag")
        Environment.default.register_tag(name, klass)
      end

      # Pass a module with filter methods which should be available
      # to all liquid views. Good for registering the standard library
      def register_filter(mod)
        Deprecations.warn("Template.register_filter", "Environment#register_filter")
        Environment.default.register_filter(mod)
      end

      private def default_resource_limits=(limits)
        Deprecations.warn("Template.default_resource_limits=", "Environment#default_resource_limits=")
        Environment.default.default_resource_limits = limits
      end

      def default_resource_limits
        Environment.default.default_resource_limits
      end

View on GitHub (pinned to 807d45a6b3)