mislav/will_paginate · error · ArgumentError

:renderer not specified

Error message

:renderer not specified

What it means

will_paginate's view helper resolves a renderer object via a case on options[:renderer]; the nil branch raises ArgumentError ':renderer not specified'. A renderer is normally injected for you: the gem's Rails integration seeds WillPaginate::ViewHelpers.pagination_options[:renderer] (e.g. WillPaginate::ActionView::LinkRenderer), so hitting this nil branch means that global default was never set or was cleared.

Source

Thrown at lib/will_paginate/view_helpers.rb:83

    #   <%= will_paginate @posts, :style => 'color:blue' %>
    #
    # will result in:
    #
    #   <div class="pagination" style="color:blue"> ... </div>
    #
    def will_paginate(collection, options = {})
      # early exit if there is nothing to render
      return nil unless collection.total_pages > 1

      options = WillPaginate::ViewHelpers.pagination_options.merge(options)

      options[:previous_label] ||= will_paginate_translate(:previous_label) { '&#8592; Previous' }
      options[:next_label]     ||= will_paginate_translate(:next_label) { 'Next &#8594;' }

      # get the renderer instance
      renderer = case options[:renderer]
      when nil
        raise ArgumentError, ":renderer not specified"
      when String
        klass = if options[:renderer].respond_to? :constantize then options[:renderer].constantize
          else Object.const_get(options[:renderer]) # poor man's constantize
          end
        klass.new
      when Class then options[:renderer].new
      else options[:renderer]
      end
      # render HTML for pagination
      renderer.prepare collection, options, self
      output = renderer.to_html
      output = output.html_safe if output.respond_to?(:html_safe)
      output
    end

    # Renders a message containing number of displayed vs. total entries.
    #
    #   <%= page_entries_info @posts %>

View on GitHub (pinned to 50017c3eb0)

Solutions

1. Set the global default once at boot: WillPaginate::ViewHelpers.pagination_options[:renderer] ||= WillPaginate::ActionView::LinkRenderer
2. Or pass it per call: will_paginate(@posts, renderer: WillPaginate::ActionView::LinkRenderer)
3. Verify the Rails integration is loaded (require 'will_paginate' / the railtie fires) and fix any initializer that overwrites pagination_options instead of merging into it

Example fix

// before
# config/initializers/will_paginate.rb had overwritten options and dropped :renderer
WillPaginate::ViewHelpers.pagination_options = { previous_label: '<<', next_label: '>>' }

// after
WillPaginate::ViewHelpers.pagination_options.merge!(previous_label: '<<', next_label: '>>')
WillPaginate::ViewHelpers.pagination_options[:renderer] ||= WillPaginate::ActionView::LinkRenderer

# fail fast at boot instead of mid-request in a view
raise ':renderer not specified: set WillPaginate::ViewHelpers.pagination_options[:renderer]' unless WillPaginate::ViewHelpers.pagination_options[:renderer]

def will_paginate_renderer_configured?
  !WillPaginate::ViewHelpers.pagination_options[:renderer].nil?
end

begin
  = will_paginate @posts
rescue ArgumentError => e
  raise unless e.message == ':renderer not specified'
  # last-resort: pass the renderer explicitly
  render partial: 'shared/pager', locals: { collection: @posts, renderer: WillPaginate::ActionView::LinkRenderer }
end

When it happens

Trigger: Calling WillPaginate::ViewHelpers#will_paginate outside the wired environment (plain ERB through a non-Rails stack, Sinatra/hand-rolled views, a Rails console/preview context that never loaded the railtie), or app code that resets/merges over WillPaginate::ViewHelpers.pagination_options and drops :renderer.

Common situations: Using the gem in a non-Rails project without requiring a renderer; an initializer that assigns pagination_options = {...} wholesale instead of merging; a gem load-order problem where the railtie never ran; upgrading and a custom bootstrap stopped requiring 'will_paginate/action_view'.

Related errors

• The #{collection_name} variable appears to be empty. Did you
• :page parameter required
• unsupported parameters: %p
• invalid #{name}: #{value.inspect}
• DEPRECATION WARNING: #{message} (called from #{offending_lin

AI-assisted analysis of mislav/will_paginate@50017c3eb0 (2026-08-21). Data as JSON: /api/errors/9a413fd2a7ce56ec. Report an issue: GitHub.