{"record":{"id":"2a4152778b184286","repo":"basecamp/kamal","slug":"file-path-is-required","errorCode":null,"errorMessage":"file path is required","messagePattern":"file path is required","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/kamal/output/file_logger.rb","lineNumber":5,"sourceCode":"class Kamal::Output::FileLogger < Kamal::Output::BaseLogger\n  attr_reader :path\n\n  def self.build(settings:, config:)\n    raise ArgumentError, \"file path is required\" unless settings[\"path\"]\n    new(path: settings[\"path\"])\n  end\n\n  def initialize(path:)\n    @path = Pathname.new(path)\n    super()\n  end\n\n  def <<(message)\n    @file&.print(message)\n  end\n\n  private\n    def on_start(payload)\n      path.mkpath\n      @file_path = path.join(filename_for(payload))\n      @file = File.open(@file_path, \"a\")\n      @file.sync = true","sourceCodeStart":1,"sourceCodeEnd":23,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/output/file_logger.rb#L1-L23","documentation":"Kamal raises ArgumentError \"file path is required\" when the output.file logger is enabled in deploy.yml but its settings hash has no path key. FileLogger.build (lib/kamal/output/file_logger.rb:5) is called from Kamal::Configuration::Output#build_loggers for the output: file: entry, so this fails at config load time before any command runs.","triggerScenarios":"deploy.yml containing output: file: with an empty or null value, or a file: mapping that lacks path, e.g. output: { file: null } (settings become {} and settings[\"path\"] is nil).","commonSituations":"Enabling file logging by copying a truncated example; adding output: file: as a placeholder intending to configure it later; YAML indentation that puts path under the wrong level.","solutions":["Add the path setting under file: in deploy.yml","Use an absolute path or a path relative to the app root, and make sure the directory exists and is writable by the user running kamal","If you did not intend file logging, remove the output: file: entry entirely"],"exampleFix":"# deploy.yml (before)\noutput:\n  file:\n\n# deploy.yml (after)\noutput:\n  file:\n    path: log/kamal.log","handlingStrategy":"validation","validationCode":"require \"yaml\"\n\nconfig = YAML.load_file(\"config/deploy.yml\", aliases: true)\nfile_output = config.dig(\"output\", \"file\")\nif !file_output.nil? && file_output.to_h[\"path\"].to_s.empty?\n  abort \"output.file requires a path setting\"\nend","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never commit `output: file:` as a stub; always include path","Verify logging config with `kamal config` after editing the output section"],"tags":["kamal","logging","configuration","file-output"],"backgroundTag":"missing-required-config-key","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}