❓ FAQ / Troubleshooting
Practical answers to common questions and failure modes when working with rails-crons.
🧠 General
Q: Does rails-crons replace Sidekiq-Cron or Rufus?
No — it complements them.
rails-crons handles safe scheduling and dispatch (exactly-once ticks across nodes).
You can still use Sidekiq or ActiveJob for actual job execution.
Q: Why not just use system cron or Heroku Scheduler?
Those work fine for small apps but don’t scale well:
- Each node runs its own crontab → duplicate jobs
- No distributed locks or visibility
- Harder to version control with code
rails-crons solves all three while staying 100% Ruby-native.
Q: Can I use it without Rails?
Yes. It can run in plain Ruby apps too — just require the gem and configure manually:
require "rails_cron"
RailsCron.configure do |c|
c.lock_adapter = RailsCron::Lock::Redis.new(url: "redis://localhost:6379/0")
end
RailsCron.start!
⚙️ Configuration Issues
Q: My jobs run multiple times across nodes. Why?
Check your lock_adapter configuration — You must use Redis or Postgres for distributed safety. The in-memory lock adapter only prevents duplicates within the same process.
Q: How often should I set tick_interval?
- 5 seconds is a safe default for most workloads.
- For high-frequency tasks, lower it to 1–2 seconds.
- For lightweight daily jobs, you can increase it to 10–15 seconds.
Q: What does window_lookback do?
It defines how far back the scheduler looks for missed ticks (e.g., after downtime). If a node was offline for 2 minutes, and window_lookback = 120, it will replay any missed jobs within that window.
🔒 Lock Adapters
Q: Redis vs Postgres — which one should I use?
| Environment | Recommended Adapter | Notes |
|---|---|---|
| Production (multi-node) | Redis | Fastest and simplest distributed locks |
| Postgres-only setup | Postgres | Works even without Redis; slightly slower |
| Local dev / testing | Memory | Single-process only (no cross-node locking) |
Q: What happens if the scheduler crashes mid-tick?
Each cron tick is idempotent and tied to a unique idempotency_key. If the process crashes, another node can safely acquire the next tick without causing duplicate job executions.
🧰 CLI & Tasks
Q: How do I test a cron manually?
bin/rails rails_cron:tick
This triggers one scheduler tick immediately — useful for testing or debugging.
Q: How do I verify my configuration?
bin/rails rails_cron:status
Displays:
- Active lock adapter
- Tick interval and lookback window
- Registered jobs with their cron schedules
🧯 Operational
Q: Is it safe to restart the scheduler during deployment?
Yes. The scheduler gracefully traps TERM and INT signals, finishes the current tick, and exits cleanly.
If multiple schedulers start, the lock ensures only one node dispatches at a time.
Q: Can I run multiple schedulers for redundancy?
Yes. Run as many instances as you want — only one will acquire the lock for each tick, the rest stay idle until the lock expires.
Q: How can I debug skipped or delayed jobs?
- Check your
window_lookbacksetting. - Ensure your Redis or Postgres connection is stable.
- Enable detailed logs with:
Rails.logger.level = :debug
Still stuck?
- Raise an issue on the project’s GitHub with details about your setup, Postgres version, and any relevant logs.
- We offer Professional support for complex issues or custom integrations. Contact us at sales@codevedas.com for inquiries.