ruby/ruby · error · ArgumentError

unknown platform #{platform_name.inspect}

Error message

unknown platform #{platform_name.inspect}

What it means

In the RubyGems dependencies DSL, every platform passed to `gem 'x', platform(s):` (or inside a `platform :foo do ... end` block) is looked up in PLATFORM_MAP. A symbol not present there raises ArgumentError immediately. Supported names include :ruby/:ruby_XY, :mri/:mri_XY, :mingw, :x64_mingw, :mswin, :mswin64, :jruby, :maglev, :rbx (and their _XY variants).

Source

Thrown at lib/rubygems/request_set/gem_dependency_api.rb:543

    true
  end

  private :gem_source

  ##
  # Handles the platforms: option from +options+.  Returns true if the
  # platform matches the current platform.

  def gem_platforms(name, options) # :nodoc:
    platform_names = Array(options.delete(:platform))
    platform_names.concat Array(options.delete(:platforms))
    platform_names.concat @current_platforms if @current_platforms

    return true if platform_names.empty?

    platform_names.any? do |platform_name|
      raise ArgumentError, "unknown platform #{platform_name.inspect}" unless
        platform = PLATFORM_MAP[platform_name]

      next false unless Gem::Platform.match_gem? platform, name

      if engines = ENGINE_MAP[platform_name]
        next false unless engines.include? Gem.ruby_engine
      end

      case WINDOWS[platform_name]
      when :only then
        next false unless Gem.win_platform?
      when :never then
        next false if Gem.win_platform?
      end

      VERSION_MAP[platform_name].satisfied_by? Gem.ruby_version
    end
  end

View on GitHub (pinned to 0e5b888e1c)

Solutions

1. Use one of the recognized names: :ruby, :mri, :mingw, :x64_mingw, :mswin, :mswin64, :jruby, :maglev, :rbx (optionally with _XY version suffixes)
2. For unix-like non-windows MRI, use :ruby or :mri instead of :linux/:macos
3. Fix the typo so the symbol matches a PLATFORM_MAP key exactly

Example fix

# before
gem 'libv8', platforms: :macos

# after
gem 'libv8', platforms: :ruby

VALID = %i[ruby mri mingw x64_mingw mswin mswin64 jruby maglev rbx].freeze
bad = platforms.reject { |p| VALID.include?(p.to_s.sub(/_\d+\z/, '').to_sym) }
abort "unknown platforms: #{bad.inspect}" unless bad.empty?
# then write/use `gem 'x', platforms: ...`

begin
  Gem::RequestSet.new.import(gems_rb)
rescue ArgumentError => e
  raise if !e.message.include?('unknown platform')
  abort "#{gems_rb}: #{e.message} - allowed: :ruby, :mri, :mingw, :x64_mingw, :mswin, :mswin64, :jruby, :maglev, :rbx"
end

When it happens

Trigger: `gem 'x', platforms: :macos` (macos/darwin is not a recognized platform here), a typo like :mignw, or a Bundler-only/legacy name such as :mswin_19. The lookup is PLATFORM_MAP[platform_name] inside gem_platforms, raised before any matching logic runs.

Common situations: Copying Bundler Gemfile platform symbols into a gems.rb processed by RubyGems itself; assuming OS-based names (:linux, :macos, :windows) exist in this DSL - only :windows-style entries like mswin/mingw are modeled; typos from hand-editing.

Related errors

• invalid gemspec #{spec_file}
• no gemspecs found at #{Dir.pwd}
• Unhandled gem options #{options.inspect}
• duplicate source #{source_description} for gem #{name}
• You must specify engine_version along with the Ruby engine

AI-assisted analysis of ruby/ruby@0e5b888e1c (2026-08-21). Data as JSON: /api/errors/a20469e1694df8cf. Report an issue: GitHub.