github/markup · error · ArgumentError

The '#{symbol}' symbol is already defined.

Error message

The '#{symbol}' symbol is already defined.

What it means

GitHub::Markup.markup_impl raises ArgumentError "The '#{symbol}' symbol is already defined." when a renderer is registered under a symbol that already has an entry in the @@markups registry. The registry is populated when the gem is required (lib/github/markups registers :markdown, :rst, :asciidoc, etc.), and both markup() and command() funnel through markup_impl(), which refuses to overwrite an existing key. This protects the symbol -> implementation lookup used by render_s from silently replacing a renderer.

Source

Thrown at lib/github/markup.rb:67

    def render_s(symbol, content, options: {})
      raise ArgumentError, 'Can not render a nil.' if content.nil?

      if markups.key?(symbol)
        markups[symbol].render(nil, content, options: options)
      else
        content
      end
    end

    def markup(symbol, gem_name, regexp, languages, opts = {}, &block)
      impl = GemImplementation.new(regexp, languages, gem_name, &block)
      markup_impl(symbol, impl)
    end

    def markup_impl(symbol, impl)
      if markups.key?(symbol)
        raise ArgumentError, "The '#{symbol}' symbol is already defined."
      end
      markups[symbol] = impl
    end

    def command(symbol, command, regexp, languages, name, &block)
      if File.exist?(file = File.dirname(__FILE__) + "/commands/#{command}")
        command = file
      end

      impl = CommandImplementation.new(regexp, languages, command, name, &block)
      markup_impl(symbol, impl)
    end

    def can_render?(filename, content, symlink: false)
      renderer(filename, content, symlink: symlink) != nil
    end

    def renderer(filename, content, symlink: false)

View on GitHub (pinned to 76e2682193)

Solutions

1. Register the custom renderer under a fresh, unused symbol (GitHub::Markup.markup(:myengine, 'myengine-gem', /myext\z/, []).
2. Find and eliminate the double load: ensure the registration file is require'd once, or wrap it with `unless GitHub::Markup.markups.key?(:your_symbol)`.
3. If you intend to replace a built-in renderer, remove/monkey-patch the default registration in lib/github/markups rather than re-registering the same symbol.
4. Search the codebase and Gemfile.lock for other gems calling GitHub::Markup.markup/command with the colliding symbol.

Example fix

# before
# config/initializers/markup.rb - raises on Rails dev reload
GitHub::Markup.command(:creole, 'creole', /creole\z/, [])

# after
unless GitHub::Markup.markups.key?(:creole)
  GitHub::Markup.command(:creole, 'creole', /creole\z/, [])
end

# Guard custom registrations against re-registration (Rails dev reload, double require):
unless GitHub::Markup.markups.key?(:myengine)
  GitHub::Markup.markup(:myengine, 'myengine-gem', /myext\z/, [])
end

begin
  GitHub::Markup.markup_impl(:custom, impl)
rescue ArgumentError => e
  raise unless e.message.include?('already defined')
  # idempotent boot: symbol already registered by an earlier load, keep the existing one
  log.info('markup :custom already registered; skipping')
end

When it happens

Trigger: Calling GitHub::Markup.markup(:markdown, ...) or GitHub::Markup.command(:rst, ...) for a symbol the default lib/github/markups file already registered; a custom markups registration file being loaded twice (double require, Rails dev reloading, autoload/eager-load overlap); two gems/initializers both registering the same symbol.

Common situations: An initializer that adds a custom renderer and gets re-evaluated on each Rails dev reload; copying the gem's own registration block and forgetting to change the symbol; a gem dependency that also registers renderers colliding with the app's; upgrading github-markup and not noticing a symbol your code reuses was added upstream.

Related errors

• stderr
• Can not render a nil.
• subclasses of GitHub::Markup::Implementation must define #re
• unknown commonmarker option: #{opt.inspect}
• unknown commonmarker extension: #{ext.inspect}

AI-assisted analysis of github/markup@76e2682193 (2026-08-21). Data as JSON: /api/errors/c4682659bd1ab074. Report an issue: GitHub.