ruby/ruby · error · Gem::CommandLineError

Please specify an executable to run (e.g. #{program_name} CO

Error message

Please specify an executable to run (e.g. #{program_name} COMMAND)

What it means

`gem exec COMMAND [args]` runs an executable provided by an installed gem; check_executable raises Gem::CommandLineError when options[:executable] is nil - i.e. no COMMAND was given after `gem exec`. The check runs during argument validation, before any gem environment is set up, so nothing executes.

Source

Thrown at lib/rubygems/commands/exec_command.rb:116

      if options[:version].none?
        options[:version] = Gem::Requirement.new(gem_version)
      else
        options[:version].concat [gem_version]
      end
    end

    if options[:prerelease] && !options[:version].prerelease?
      if options[:version].none?
        options[:version] = Gem::Requirement.default_prerelease
      else
        options[:version].concat [Gem::Requirement.default_prerelease]
      end
    end
  end

  def check_executable
    if options[:executable].nil?
      raise Gem::CommandLineError,
        "Please specify an executable to run (e.g. #{program_name} COMMAND)"
    end
  end

  def print_command
    verbose "running #{program_name} with:\n"
    opts = options.reject {|_, v| v.nil? || Array(v).empty? }
    max_length = opts.map {|k, _| k.size }.max
    opts.each do |k, v|
      next if v.nil?
      verbose "\t#{k.to_s.rjust(max_length)}: #{v}"
    end
    verbose ""
  end

  def install_if_needed
    activate!
  rescue Gem::MissingSpecError

View on GitHub (pinned to 0e5b888e1c)

Solutions

Name the executable: gem exec rake -T
Guard the variable in scripts: ${TOOL:?tool name required}
Use bundle exec inside Bundler projects; gem exec is for gem-installed tools

Example fix

# before
ENTRYPOINT ["gem", "exec"]     # no COMMAND -> error
# or
gem exec $TOOL                  # TOOL unset

# after
ENTRYPOINT ["gem", "exec", "rake"]
: "${TOOL:?TOOL must be set}"; gem exec "$TOOL"

Defensive patterns

Strategy: validation

Validate before calling

tool = ARGV.shift
abort 'Please specify an executable to run (e.g. gem exec COMMAND)' if tool.nil? || tool.empty?
exec('gem', 'exec', tool, *ARGV)

Try / catch

begin
  Gem::Commands::ExecCommand.new.invoke(*args)
rescue Gem::CommandLineError => e
  raise unless e.message.include?('executable to run')
  abort 'usage: gem exec COMMAND [options]'
end

Prevention

Give wrappers an explicit default command or fail fast on empty variables
Remember gem exec does not enumerate executables when run bare
Prefer bundle exec inside Bundler projects; reserve gem exec for gem-installed tools

When it happens

Trigger: `gem exec` with no arguments; `gem exec --keep-files` style invocations where only flags are present; wrappers forwarding an empty variable (gem exec $TOOL with TOOL unset).

Common situations: Docker ENTRYPOINT ['gem','exec'] or CI wrappers forwarding a possibly-empty variable; users expecting bare `gem exec` to list available executables (it does not).

Related errors

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