ruby-concurrency/concurrent-ruby · error · ArgumentError

:load_factor must be a number between 0 and 1

Error message

:load_factor must be a number between 0 and 1

What it means

As part of the same options validation, validate_options_hash! (map.rb:347-349) requires :load_factor to be a Numeric strictly greater than 0 and at most 1 (the hash-table growth threshold, mirroring Java's ConcurrentHashMap). Zero, negative values, values above 1, and non-Numeric values raise ArgumentError at construction.

Source

Thrown at lib/concurrent-ruby/concurrent/map.rb:346

      raise KeyError, 'key not found'
    end

    def initialize_copy(other)
      super
      populate_from(other)
    end

    def populate_from(hash)
      hash.each_pair { |k, v| self[k] = v }
      self
    end

    def validate_options_hash!(options)
      if (initial_capacity = options[:initial_capacity]) && (!initial_capacity.kind_of?(Integer) || initial_capacity < 0)
        raise ArgumentError, ":initial_capacity must be a positive Integer"
      end
      if (load_factor = options[:load_factor]) && (!load_factor.kind_of?(Numeric) || load_factor <= 0 || load_factor > 1)
        raise ArgumentError, ":load_factor must be a number between 0 and 1"
      end
    end
  end
end

View on GitHub (pinned to 0b88d5ff75)

Solutions

1. Pass a Float in (0, 1]: Concurrent::Map.new(load_factor: 0.75).
2. Cast and range-check config at the boundary: lf = Float(cfg['load_factor']); raise unless (0..1].cover?(lf).
3. Clamp computed values into range: [[lf, 0.01].max, 1.0].min.

Example fix

# before
map = Concurrent::Map.new(load_factor: cfg['load_factor']) # '0.75' or 0 raises ArgumentError

# after
lf = Float(cfg.fetch('load_factor', 0.75))
map = Concurrent::Map.new(load_factor: [[lf, 0.01].max, 1.0].min)

def map_load_factor(raw)
  lf = Float(raw)
  raise ArgumentError, ':load_factor must be in (0, 1]' unless lf.positive? && lf <= 1
  lf
end
Concurrent::Map.new(load_factor: map_load_factor(cfg['load_factor']))

When it happens

Trigger: Concurrent::Map.new(load_factor: 0); load_factor: 1.5; load_factor: '0.75' from stringly-typed config; load_factor: nil-coerced arithmetic producing 0.

Common situations: Copying Java tuning values without checking the (0, 1] range; environment/YAML-sourced floats arriving as strings; computed load factors that underflow to 0.

Related errors

• :initial_capacity must be a positive Integer
• executor not recognized by '#{executor_identifier}'
• unbuffered channels cannot have a capacity
• capacity must be at least 1 for this buffer type
• no block given

AI-assisted analysis of ruby-concurrency/concurrent-ruby@0b88d5ff75 (2026-08-21). Data as JSON: /api/errors/6737886fb32e8ce8. Report an issue: GitHub.