javan/whenever · error · ArgumentError

:command, :path, & :flags are required

Error message

:command, :path, & :flags are required

What it means

Whenever's Capistrano 2 integration runs the whenever binary on your servers via whenever_run_commands, which requires an args hash containing :command, :path, and :flags. It raises this ArgumentError when any of those three keys is missing. The stock tasks in lib/whenever/capistrano/v2/recipes.rb (whenever:update_crontab, whenever:clear_crontab) always build the full hash, so in practice only custom tasks or reimplemented recipes that call the helper directly hit this guard. Note the check is key presence (args.include?), not nil values.

Source

Thrown at lib/whenever/capistrano/v2/support.rb:39

            map
          end
        end

        def whenever_prepare_for_rollback args
          if fetch(:previous_release)
            # rollback to the previous release's crontab
            args[:path] = fetch(:previous_release)
          else
            # clear the crontab if no previous release
            args[:path]  = fetch(:release_path)
            args[:flags] = fetch(:whenever_clear_flags)
          end
          args
        end

        def whenever_run_commands(args)
          unless [:command, :path, :flags].all? { |a| args.include?(a) }
            raise ArgumentError, ":command, :path, & :flags are required"
          end

          whenever_server_roles.each do |server, roles|
            roles_arg = roles.empty? ? "" : " --roles #{roles.join(',')}"

            command = "cd #{args[:path]} && #{args[:command]} #{args[:flags]}#{roles_arg}"
            run command, whenever_options.merge(:hosts => server)
          end
        end

      end
    end
  end
end

View on GitHub (pinned to 756163ed1a)

Solutions

1. Use the built-in tasks whenever:update_crontab and whenever:clear_crontab from lib/whenever/capistrano/v2/recipes.rb instead of calling whenever_run_commands yourself.
2. If you call the helper directly, pass all three keys: command: fetch(:whenever_command), flags: fetch(:whenever_update_flags) (or :whenever_clear_flags), path: fetch(:whenever_path).
3. Make sure custom tasks run after require 'whenever/capistrano' so the helper and its _cset defaults are loaded.
4. Wrap the call in rescue ArgumentError and re-raise with your task name to pinpoint which custom task built the bad hash.

Example fix

# before (custom task, raises ':command, :path, & :flags are required')
namespace :custom do
  task :cron do
    whenever_run_commands(
      command: 'whenever',
      flags:   '--update-crontab myapp --set environment=production'
    )
  end
end

# after
namespace :custom do
  task :cron do
    whenever_run_commands(
      command: fetch(:whenever_command),
      flags:   fetch(:whenever_update_flags),
      path:    fetch(:whenever_path)
    )
  end
end

required = %i[command path flags]
missing = required - args.keys
unless missing.empty?
  abort('whenever args missing: ' + missing.join(', ') + ' in ' + task_name)
end
whenever_run_commands(args)

def whenever_args_complete?(args)
  args.is_a?(Hash) && %i[command path flags].all? { |k| args.key?(k) }
end

begin
  whenever_run_commands(args)
rescue ArgumentError => e
  raise ArgumentError, 'custom whenever task built bad args: ' + e.message
end

When it happens

Trigger: Calling whenever_run_commands from a custom Capistrano task or callback with a partial hash, e.g. whenever_run_commands(command: 'whenever', flags: '--clear-crontab myapp') with no :path. Redefining the stock recipes inside deploy.rb (to add bundle exec or a custom user) and dropping one key. Invoking the helper from a namespace loaded before whenever/capistrano so the _cset defaults behind fetch(:whenever_command) etc. are not yet defined.

Common situations: Legacy Capistrano 2.x deploy.rb files copied from blog posts that reimplement the whenever tasks; teams adding roles/hosts logic and rebuilding the args hash from scratch instead of reusing fetch(:whenever_command), fetch(:whenever_update_flags), fetch(:whenever_path); upgrading whenever within Capistrano 2.x and missing a newly required key.

Related errors

• You cannot specify an ':at' when using the shortcuts for tim
• Time must be in minutes or higher
• Couldn't parse: #{@time.inspect}
• #{must_be_between}, #{at.min} given
• #{must_be_between}, #{at.max} given

AI-assisted analysis of javan/whenever@756163ed1a (2026-08-21). Data as JSON: /api/errors/69d0b1bc12ff79d5. Report an issue: GitHub.