{"record":{"id":"257d077b8b548af6","repo":"basecamp/kamal","slug":"no-servers-specified-for-the-role-name-role-yo","errorCode":null,"errorMessage":"No servers specified for the #{role.name} role. You can ignore this with allow_empty_roles: true","messagePattern":"No servers specified for the #(.+?) role\\. You can ignore this with allow_empty_roles: true","errorType":"validation","errorClass":"Kamal::ConfigurationError","httpStatus":null,"severity":"error","filePath":"lib/kamal/configuration.rb","lineNumber":354,"sourceCode":"      end\n\n      raise Kamal::ConfigurationError, \"Missing required configuration for image\" if image.blank?\n\n      if raw_config.servers.nil?\n        raise Kamal::ConfigurationError, \"No servers or accessories specified\" unless raw_config.accessories.present?\n      else\n        unless role(primary_role_name).present?\n          raise Kamal::ConfigurationError, \"The primary_role #{primary_role_name} isn't defined\"\n        end\n\n        if primary_role.hosts.empty?\n          raise Kamal::ConfigurationError, \"No servers specified for the #{primary_role.name} primary_role\"\n        end\n\n        unless allow_empty_roles?\n          roles.each do |role|\n            if role.hosts.empty?\n              raise Kamal::ConfigurationError, \"No servers specified for the #{role.name} role. You can ignore this with allow_empty_roles: true\"\n            end\n          end\n        end\n      end\n\n      true\n    end\n\n    def ensure_valid_service_name\n      raise Kamal::ConfigurationError, \"Service name can only include alphanumeric characters, hyphens, and underscores\" unless raw_config[:service] =~ /^[a-z0-9_-]+$/i\n\n      true\n    end\n\n    def ensure_valid_kamal_version\n      if minimum_version && Gem::Version.new(minimum_version) > Gem::Version.new(Kamal::VERSION)\n        raise Kamal::ConfigurationError, \"Current version is #{Kamal::VERSION}, minimum required is #{minimum_version}\"\n      end","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration.rb#L336-L372","documentation":"After validating the primary role, Kamal iterates every role and requires each non-primary role to have at least one host, unless `allow_empty_roles: true` is set. This Kamal::ConfigurationError fires for the first role whose hosts array is empty, with the role name in the message and a pointer to the escape hatch. The check exists because silently skipping an empty role usually masks a templating mistake.","triggerScenarios":"`servers: { web: [...], workers: { hosts: [] } }` with no `allow_empty_roles: true`; ERB-generated role hosts (e.g. sidekiq hosts from an env var) that render empty in one environment; a role temporarily emptied while migrating infrastructure.","commonSituations":"Multi-environment configs where workers exist in production but not staging; host lists driven by ENV that are unset locally; role pruning during scale-down that leaves the key behind.","solutions":["Populate the empty role's hosts list if the role should really deploy.","If the role is legitimately empty in this environment, add top-level `allow_empty_roles: true` (or set it per environment).","Remove the role key entirely if you no longer need it — cleaner than keeping an empty entry.","Make ERB host lists raise on missing input rather than rendering []."],"exampleFix":"# config/deploy.yml — before\nservers:\n  web:\n    - 1.2.3.4\n  workers:\n    hosts: []\n\n# after\nallow_empty_roles: true\nservers:\n  web:\n    - 1.2.3.4\n  workers:\n    hosts: []","handlingStrategy":"validation","validationCode":"def roles_have_hosts_unless_allowed?(path = \"config/deploy.yml\")\n  raw = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) || {}\n  return true if raw[\"allow_empty_roles\"]\n  primary = raw[\"primary_role\"] || \"web\"\n  raw[\"servers\"].to_a.all? do |name, entry|\n    hosts = entry.is_a?(Hash) ? entry[\"hosts\"] : entry\n    name == primary || Array(hosts).any?\n  end\nend","typeGuard":null,"tryCatchPattern":"begin\n  config = Kamal::Configuration.new(create_config_files: false)\nrescue Kamal::ConfigurationError => e\n  puts \"Deploy config invalid: #{e.message}\"\n  exit 1\nend","preventionTips":["Set `allow_empty_roles: true` only in environment overlays that genuinely lack optional roles.","Delete role keys you no longer use rather than emptying them.","Make ERB host arrays raise on missing input instead of emitting []."],"tags":["kamal","configuration","roles","servers"],"backgroundTag":"empty-config-list","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}