{"record":{"id":"68be2eeffb2a5411","repo":"puma/puma","slug":"workers-must-be-an-integer-or-auto","errorCode":null,"errorMessage":"workers must be an Integer or :auto","messagePattern":"workers must be an Integer or :auto","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/puma/configuration.rb","lineNumber":450,"sourceCode":"    def require_processor_counter\n      require 'concurrent/utility/processor_counter'\n    rescue LoadError\n      warn <<~MESSAGE\n        WEB_CONCURRENCY=auto or workers(:auto) requires the \"concurrent-ruby\" gem to be installed.\n        Please add \"concurrent-ruby\" to your Gemfile.\n      MESSAGE\n      raise\n    end\n\n    def parse_workers(value)\n      if value == :auto || value == 'auto'\n        require_processor_counter\n        Integer(::Concurrent.available_processor_count)\n      else\n        Integer(value)\n      end\n    rescue ArgumentError, TypeError\n      raise ArgumentError, \"workers must be an Integer or :auto\"\n    end\n\n    # Load and use the normal Rack builder if we can, otherwise\n    # fallback to our minimal version.\n    def rack_builder\n      # Load bundler now if we can so that we can pickup rack from\n      # a Gemfile\n      if @puma_bundler_pruned\n        begin\n          require 'bundler/setup'\n        rescue LoadError\n        end\n      end\n\n      begin\n        require 'rack'\n        require 'rack/builder'\n        ::Rack::Builder","sourceCodeStart":432,"sourceCodeEnd":468,"githubUrl":"https://github.com/puma/puma/blob/b8341dc946f0a2444e5ea6730d1967ca53c8d006/lib/puma/configuration.rb#L432-L468","documentation":"ArgumentError from Puma::Configuration#parse_workers (lib/puma/configuration.rb:450): worker counts must be an Integer, an integer-like string, or 'auto'/:auto (which resolves to Concurrent.available_processor_count). Anything Integer() cannot coerce — '2.5', 'two', '  ', or a wrong-typed value — is re-raised with this message. It flows from the workers DSL (lib/puma/dsl.rb:739) and from the WEB_CONCURRENCY environment variable read at lib/puma/configuration.rb:250.","triggerScenarios":"workers \"2.5\" or workers :four in config/puma.rb; ENV['WEB_CONCURRENCY'] set to 'two', '2.5', or a stray character via .env, docker-compose, or CI secrets. Note nil is legal for the DSL (means 0), and strings like '2' are fine because Integer('2') works; only 'auto' is special-cased.","commonSituations":"Typo'd WEB_CONCURRENCY in deployment tooling (Capistrano, Kamal, Heroku config vars); .env files with trailing characters or units ('2 workers'); configs passing a Float; scripts exporting variables with quotes/whitespace corruption.","solutions":["Set WEB_CONCURRENCY to a plain integer string ('2') or 'auto'","In config/puma.rb use workers Integer(workers_count) or workers :auto — never a float or free text","Inspect the actual value at deploy time: p \"WEB_CONCURRENCY=#{ENV['WEB_CONCURRENCY'].inspect}\" before starting Puma","Fix the source (docker-compose env, .env, CI variable) rather than overriding in the config file"],"exampleFix":"# docker-compose.yml — before\nenvironment:\n  - WEB_CONCURRENCY=two\n\n# after\nenvironment:\n  - WEB_CONCURRENCY=2","handlingStrategy":"validation","validationCode":"# deploy-time guard before booting Puma\nif (w = ENV['WEB_CONCURRENCY'])\n  raise ArgumentError, \"WEB_CONCURRENCY must be an integer or 'auto', got #{w.inspect}\" unless w.match?(/\\A\\d+\\z|\\Aauto\\z/)\nend","typeGuard":"def valid_workers?(v) = v.nil? || v == :auto || v == 'auto' || (Integer(v) rescue false)","tryCatchPattern":"# wrapper starting Puma with a clear failure message\nbegin\n  require 'puma/launcher' # or shell out to `bundle exec puma`\nrescue ArgumentError => e\n  abort \"puma config/ENV error: #{e.message} (check WEB_CONCURRENCY=#{ENV['WEB_CONCURRENCY'].inspect})\"\nend","preventionTips":["Validate WEB_CONCURRENCY in .env samples and CI with a strict /\\A(\\d+|auto)\\z/ regex","Never store worker counts as floats or with units ('2 workers') in orchestration files","Print the resolved value (inspect, not to_s) in deploy logs so hidden whitespace/typos are visible"],"tags":["configuration","cluster-mode","workers","web-concurrency","env-var","boot"],"backgroundTag":"invalid-config-value","analyzedSha":"b8341dc946f0a2444e5ea6730d1967ca53c8d006","analyzedAt":"2026-08-21T18:40:40.221Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}