{"record":{"id":"ebb5d07db731d7f8","repo":"ankane/pghero","slug":"invalid-config-file","errorCode":null,"errorMessage":"Invalid config file","messagePattern":"Invalid config file","errorType":"exception","errorClass":"PgHero::Error","httpStatus":null,"severity":"critical","filePath":"lib/pghero.rb","lineNumber":120,"sourceCode":"    def file_config\n      unless defined?(@file_config)\n        require \"erb\"\n        require \"yaml\"\n\n        path = config_path\n\n        config_file_exists = File.exist?(path)\n\n        config = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) if config_file_exists\n        config ||= {}\n\n        @file_config =\n          if config[env]\n            config[env]\n          elsif config[\"databases\"] # preferred format\n            config\n          elsif config_file_exists\n            raise Error, \"Invalid config file\"\n          else\n            nil\n          end\n      end\n\n      @file_config\n    end\n\n    # private\n    def default_config\n      databases = {}\n\n      unless ENV[\"PGHERO_DATABASE_URL\"]\n        ActiveRecord::Base.configurations.configs_for(env_name: env, include_hidden: true).each do |db|\n          databases[db.name] = {\"spec\" => db.name}\n        end\n      end\n","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/ankane/pghero/blob/7edb57986ffd36f9d64f0830c4ccc90a5eac46d6/lib/pghero.rb#L102-L138","documentation":"PgHero.file_config reads config/pghero.yml (or PGHERO_CONFIG_PATH), renders ERB and YAML.safe_loads it. The resulting hash must either contain a key for the current environment (legacy per-env format) or a top-level \"databases\" key (preferred format). If the file exists but has neither, PgHero raises Error \"Invalid config file\" - meaning the YAML parsed fine but its shape is not recognized.","triggerScenarios":"A pghero.yml containing only top-level keys like username/password with no databases: mapping; an env mismatch where the file has a development: key but RAILS_ENV/RACK_ENV is production and no databases: key exists; a file whose YAML body is effectively empty (e.g. only ERB comments), which safe_load turns into a hash without usable keys.","commonSituations":"Migrating from the legacy per-environment format to the databases: format and leaving the file half-written; setting PGHERO_CONFIG_PATH to the wrong file; deploying with a different RAILS_ENV than the one used locally; Docker deployments where the mounted config differs per stage.","solutions":["Restructure config/pghero.yml to the preferred format with a top-level databases: key listing each database (url: or spec:)","If you must keep per-env format, add a key matching the current env exactly (e.g. production: with the db config nested under it)","Verify the environment name: print PgHero.env (from RAILS_ENV or RACK_ENV, default \"development\") and confirm the file has that key","Confirm PGHERO_CONFIG_PATH points at the intended file and the file parses: YAML.safe_load(File.read(path), aliases: true) in rails console"],"exampleFix":"# config/pghero.yml - before (no databases key, no matching env key)\nusername: admin\npassword: secret\n\n# after (preferred format)\ndatabases:\n  primary:\n    url: postgres://user:pass@localhost/mydb\nusername: admin\npassword: secret","handlingStrategy":"validation","validationCode":"# config/initializers/pghero_check.rb - fail at boot, not at first request\npath = PgHero.config_path\nif File.exist?(path)\n  require \"yaml\"\n  require \"erb\"\n  cfg = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) || {}\n  unless cfg[\"databases\"] || cfg[PgHero.env]\n    raise \"config/pghero.yml must define a top-level 'databases' key or a '#{PgHero.env}' key\"\n  end\nend","typeGuard":null,"tryCatchPattern":"begin\n  PgHero.config\nrescue PgHero::Error => e\n  # surface config problems clearly at deploy time instead of a 500 per request\n  Rails.logger.fatal(\"pghero config invalid: #{e.message}\")\n  raise\nend","preventionTips":["Standardize on the databases: format for pghero.yml and assert its shape in CI","Keep RAILS_ENV/RACK_ENV explicit in deploys so the env-key format cannot silently mismatch","Add a boot-time or deploy-time check that loads pghero.yml and validates its keys"],"tags":["pghero","config","yaml","rails"],"backgroundTag":"invalid-config-file","analyzedSha":"7edb57986ffd36f9d64f0830c4ccc90a5eac46d6","analyzedAt":"2026-08-21T17:33:54.942Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}