Shopify/liquid · error · Liquid::FileSystemError

This liquid context does not allow includes.

Error message

This liquid context does not allow includes.

What it means

Liquid's default BlankFileSystem raises Liquid::FileSystemError on any {% include %}/{% render %} because no file system was configured. Liquid refuses to load templates from disk unless you explicitly provide one (e.g. Liquid::LocalFileSystem), preventing accidental file access.

Solutions

  1. Configure a file system: Liquid::Template.file_system = Liquid::LocalFileSystem.new(root, pattern).
  2. Use BlankFileSystem deliberately only if includes should be unsupported, and remove include tags from templates.
  3. In tests, stub Template.file_system or register in-memory templates.
  4. Check that any initializer configuring the file system actually runs (e.g. Rails initializer loaded).

Example fix

// before
Liquid::Template.parse(tpl).render  # include raises
// after
Liquid::Template.file_system = Liquid::LocalFileSystem.new('templates', '%s.liquid')
Liquid::Template.parse(tpl).render
Defensive patterns

Strategy: validation

Validate before calling

def includes_configured?
  !Liquid::Template.file_system.is_a?(Liquid::BlankFileSystem)
end

Type guard

fs = Liquid::Template.file_system
fs.is_a?(Liquid::LocalFileSystem) ? fs : raise('file system not configured')

Try / catch

begin
  tpl.render(ctx)
rescue Liquid::FileSystemError => e
  raise unless e.message.include?('does not allow includes')
  configure_file_system!
  retry
end

Prevention

When it happens

Trigger: Rendering a template containing {% include 'partial' %} or {% render 'partial' %} while Liquid::Template.file_system is the default BlankFileSystem (i.e. Template.file_system was never assigned).

Common situations: Fresh Liquid setup in a non-Rails app where no file system was configured; embedding Liquid where includes were intentionally disabled; upgrading an integration that previously installed a file system.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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

Appendix: source

Thrown at lib/liquid/file_system.rb:20

module Liquid
  # A Liquid file system is a way to let your templates retrieve other templates for use with the include tag.
  #
  # You can implement subclasses that retrieve templates from the database, from the file system using a different
  # path structure, you can provide them as hard-coded inline strings, or any manner that you see fit.
  #
  # You can add additional instance variables, arguments, or methods as needed.
  #
  # Example:
  #
  #   Liquid::Template.file_system = Liquid::LocalFileSystem.new(template_path)
  #   liquid = Liquid::Template.parse(template)
  #
  # This will parse the template with a LocalFileSystem implementation rooted at 'template_path'.
  class BlankFileSystem
    # Called by Liquid to retrieve a template file
    def read_template_file(_template_path)
      raise FileSystemError, "This liquid context does not allow includes."
    end
  end

  # This implements an abstract file system which retrieves template files named in a manner similar to Rails partials,
  # ie. with the template name prefixed with an underscore. The extension ".liquid" is also added.
  #
  # For security reasons, template paths are only allowed to contain letters, numbers, and underscore.
  #
  # Example:
  #
  #   file_system = Liquid::LocalFileSystem.new("/some/path")
  #
  #   file_system.full_path("mypartial")       # => "/some/path/_mypartial.liquid"
  #   file_system.full_path("dir/mypartial")   # => "/some/path/dir/_mypartial.liquid"
  #
  # Optionally in the second argument you can specify a custom pattern for template filenames.
  # The Kernel::sprintf format specification is used.
  # Default pattern is "_%s.liquid".

View on GitHub (pinned to 807d45a6b3)