basecamp/kamal · error · ArgumentError

file path is required

Error message

file path is required

What it means

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.

Source

Thrown at lib/kamal/output/file_logger.rb:5

class Kamal::Output::FileLogger < Kamal::Output::BaseLogger
  attr_reader :path

  def self.build(settings:, config:)
    raise ArgumentError, "file path is required" unless settings["path"]
    new(path: settings["path"])
  end

  def initialize(path:)
    @path = Pathname.new(path)
    super()
  end

  def <<(message)
    @file&.print(message)
  end

  private
    def on_start(payload)
      path.mkpath
      @file_path = path.join(filename_for(payload))
      @file = File.open(@file_path, "a")
      @file.sync = true

View on GitHub (pinned to eee0083b38)

Solutions

1. Add the path setting under file: in deploy.yml
2. 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
3. If you did not intend file logging, remove the output: file: entry entirely

Example fix

# deploy.yml (before)
output:
  file:

# deploy.yml (after)
output:
  file:
    path: log/kamal.log

require "yaml"

config = YAML.load_file("config/deploy.yml", aliases: true)
file_output = config.dig("output", "file")
if !file_output.nil? && file_output.to_h["path"].to_s.empty?
  abort "output.file requires a path setting"
end

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Invalid hooks_output '#{level}'#{context}, must be one of: #
• OTel endpoint is required
• You must specify a destination
• Missing required configuration for #{key}
• Missing required configuration for image

AI-assisted analysis of basecamp/kamal@eee0083b38 (2026-08-21). Data as JSON: /api/errors/2a4152778b184286. Report an issue: GitHub.