FAQ / Troubleshooting

Can I use Kaal without a framework?

Yes. kaal supports plain Ruby setups directly.

How do I trigger one run manually? 

bundle exec kaal tick

How do I inspect current config and registered jobs? 

bundle exec kaal status

Which backend should I use?

  • memory for local development or a single in-process scheduler
  • redis for shared coordination without SQL persistence
  • sqlite for simpler SQL-backed installs
  • postgres or mysql when you want SQL persistence plus the documented shared-backend guarantee path

What exactly does Kaal guarantee?

Kaal guarantees at-most-once dispatch per (key, fire_time) for Redis, Postgres, and MySQL-backed deployments under the documented crash-and-restart model. See At-Most-Once Dispatch Guarantee.

Does Kaal guarantee exactly-once side effects?

No. Kaal guarantees scheduler dispatch semantics. Use the provided idempotency_key in your own database, queue, or API boundary when downstream effects must be effectively once.

Why is kaal init not setting up my SQL backend?

Because kaal init currently supports memory and redis only. For SQL-backed installs:

  • use kaal-sequel or kaal-activerecord in plain Ruby and configure the backend yourself
  • or use kaal-rails and run the Rails install generator

Why is boot failing before the scheduler starts?

Check:

  • config/kaal.rb exists and loads cleanly
  • the required gems for your selected backend are installed
  • REDIS_URL or DATABASE_URL is present when your setup depends on it
  • the backend adapter class matches the connection you are passing

Why are no jobs loading?

Check:

  • config/scheduler.yml exists at the configured path
  • scheduler_config_path points to the correct file
  • the YAML structure is valid
  • referenced job classes can be loaded by the app

Why am I getting duplicate-definition conflicts?

Job keys must be unique across the loaded scheduler definition set. If the same key appears more than once, Kaal treats that as a conflicting definition and the duplicate must be removed or renamed.

What happens during backend outages?

Redis and SQL-backed coordination depend on backend availability. If the backend is unavailable, ticks cannot coordinate safely and dispatch may pause or fail until the backend is healthy again. Restore backend connectivity before relying on normal scheduler operation.

Why are jobs dispatching more than once?

Check:

  • you are using redis, postgres, or mysql for the shared multi-node backend
  • enable_log_dispatch_registry = true
  • lease_ttl is at least window_lookback + tick_interval
  • each job key is unique
  • all nodes use the same namespace and scheduler definition set

See At-Most-Once Dispatch Guarantee for the full guarantee model.