{"record":{"id":"2792df1aac865fbd","repo":"Shopify/liquid","slug":"this-liquid-context-does-not-allow-includes","errorCode":null,"errorMessage":"This liquid context does not allow includes.","messagePattern":"This liquid context does not allow includes\\.","errorType":"exception","errorClass":"Liquid::FileSystemError","httpStatus":null,"severity":"error","filePath":"lib/liquid/file_system.rb","lineNumber":20,"sourceCode":"\nmodule Liquid\n  # A Liquid file system is a way to let your templates retrieve other templates for use with the include tag.\n  #\n  # You can implement subclasses that retrieve templates from the database, from the file system using a different\n  # path structure, you can provide them as hard-coded inline strings, or any manner that you see fit.\n  #\n  # You can add additional instance variables, arguments, or methods as needed.\n  #\n  # Example:\n  #\n  #   Liquid::Template.file_system = Liquid::LocalFileSystem.new(template_path)\n  #   liquid = Liquid::Template.parse(template)\n  #\n  # This will parse the template with a LocalFileSystem implementation rooted at 'template_path'.\n  class BlankFileSystem\n    # Called by Liquid to retrieve a template file\n    def read_template_file(_template_path)\n      raise FileSystemError, \"This liquid context does not allow includes.\"\n    end\n  end\n\n  # This implements an abstract file system which retrieves template files named in a manner similar to Rails partials,\n  # ie. with the template name prefixed with an underscore. The extension \".liquid\" is also added.\n  #\n  # For security reasons, template paths are only allowed to contain letters, numbers, and underscore.\n  #\n  # Example:\n  #\n  #   file_system = Liquid::LocalFileSystem.new(\"/some/path\")\n  #\n  #   file_system.full_path(\"mypartial\")       # => \"/some/path/_mypartial.liquid\"\n  #   file_system.full_path(\"dir/mypartial\")   # => \"/some/path/dir/_mypartial.liquid\"\n  #\n  # Optionally in the second argument you can specify a custom pattern for template filenames.\n  # The Kernel::sprintf format specification is used.\n  # Default pattern is \"_%s.liquid\".","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/Shopify/liquid/blob/807d45a6b3d4568e64e86b375e3702df2c7c860c/lib/liquid/file_system.rb#L2-L38","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Configure a file system: Liquid::Template.file_system = Liquid::LocalFileSystem.new(root, pattern).","Use BlankFileSystem deliberately only if includes should be unsupported, and remove include tags from templates.","In tests, stub Template.file_system or register in-memory templates.","Check that any initializer configuring the file system actually runs (e.g. Rails initializer loaded)."],"exampleFix":"// before\nLiquid::Template.parse(tpl).render  # include raises\n// after\nLiquid::Template.file_system = Liquid::LocalFileSystem.new('templates', '%s.liquid')\nLiquid::Template.parse(tpl).render","handlingStrategy":"validation","validationCode":"def includes_configured?\n  !Liquid::Template.file_system.is_a?(Liquid::BlankFileSystem)\nend","typeGuard":"fs = Liquid::Template.file_system\nfs.is_a?(Liquid::LocalFileSystem) ? fs : raise('file system not configured')","tryCatchPattern":"begin\n  tpl.render(ctx)\nrescue Liquid::FileSystemError => e\n  raise unless e.message.include?('does not allow includes')\n  configure_file_system!\n  retry\nend","preventionTips":["Configure Liquid::Template.file_system once at app boot.","Only ship BlankFileSystem if disabling includes is intentional.","Add a boot-time assertion that the file system is set where includes are needed.","Remove include tags from templates intended for include-free contexts."],"tags":["ruby","liquid","file-system","include","configuration"],"backgroundTag":"missing-config-value","analyzedSha":"807d45a6b3d4568e64e86b375e3702df2c7c860c","analyzedAt":"2026-09-08T11:31:38.917Z","contentChangedAt":"2026-09-08T11:31:38.917Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}