Shopify/liquid · error · RuntimeError

Profiler not loaded, require 'liquid/profiler' first

Error message

Profiler not loaded, require 'liquid/profiler' first

What it means

Liquid raises this plain RuntimeError when Template#parse is called with the :profile option but the profiling support classes were never loaded. Profiling code is kept out of the default load path for performance, so the caller must explicitly require 'liquid/profiler' before profiling can be enabled. configure_options checks defined?(Liquid::Profiler) and aborts parsing otherwise.

Solutions

1. Add require 'liquid/profiler' at the top of the file or Gemfile-level initializer before any parse with profile: true
2. Move the require into a boot/initializer so it runs before templates are parsed
3. Guard the profiling branch with defined?(Liquid::Profiler) and skip profiling if absent

Example fix

// before
Liquid::Template.parse(template_source, profile: true)
// after
require 'liquid/profiler'
Liquid::Template.parse(template_source, profile: true)

raise 'profiling requested but liquid/profiler not loaded' if options[:profile] && !defined?(Liquid::Profiler)
require 'liquid/profiler' if options[:profile]

def profiler_available? = defined?(Liquid::Profiler) ? true : false

When it happens

Trigger: Calling Template.parse(source, profile: true) (or Liquid::Environment with profile) without a prior require 'liquid/profiler' in the process.

Common situations: Enabling profiling in production config or an initializer while the profiler require lives only in a dev/test helper; upgrading Liquid where profiling became opt-in; copying a profiling snippet into a new app entry point.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• This liquid context does not allow includes.
• Nesting too deep
• errors.syntax.unexpected_outer_tag
• errors.syntax.unknown_tag (locale: 'Unknown tag 'tag'')
• undefined method #

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

Appendix: source

Thrown at lib/liquid/template.rb:223

        end
        @errors = context.errors
      end
    end

    def render!(*args)
      @rethrow_errors = true
      render(*args)
    end

    def render_to_output_buffer(context, output)
      render(context, output: output)
    end

    private

    def configure_options(options)
      if (profiling = options[:profile])
        raise "Profiler not loaded, require 'liquid/profiler' first" unless defined?(Liquid::Profiler)
      end

      @options      = options
      @profiling    = profiling
      @line_numbers = options[:line_numbers] || @profiling
      parse_context = if options.is_a?(ParseContext)
        options
      else
        opts = options.key?(:environment) ? options : options.merge(environment: @environment)
        ParseContext.new(opts)
      end

      @warnings = parse_context.warnings
      @error_mode = parse_context.error_mode
      parse_context
    end

    def apply_options_to_context(context, options)

View on GitHub (pinned to 807d45a6b3)