Oban
Oban
v2.15.4

View Source Troubleshooting

Jobs or Plugins aren't Running

Sometimes Cron or Pruner plugins appear to stop working unexpectedly. Typically, this happens in systems with multi-node setups where "web" nodes only enqueue jobs while "worker" nodes are configured to run queues and plugins. Most plugins require leadership to function, so When a "web" node becomes leader the plugins go dormant.

The solution is to disable leadership with peer: false on any node that doesn't run plugins, or only runs decentralized plugins like Gossip:

config :my_app, Oban, peer: false, ...

No Notifications with PgBouncer

Using PgBouncer's "Transaction Pooling" setup disables all of PostgreSQL's LISTEN and NOTIFY activity. Some functionality, such as triggering job execution, scaling queues, canceling jobs, etc. rely on those notifications.

There are several options available to ensure functional notifications:

  1. Switch to the Oban.Notifiers.PG notifier. This alternative notifier relies on Distributed Erlang and exchanges messages within a cluster. The only drawback to the PG notifier is that it doesn't trigger job insertion events.

  2. Switch PgBouncer to "Session Pooling". Session pooling isn't as resource efficient as transaction pooling, but it retains all Postgres functionality.

  3. Use a dedicated Repo that connects directly to the database, bypassing PgBouncer.

If none of those options work, the Stager will switch to local polling mode to ensure that queues keep processing jobs.

Unexpectedly Re-running All Migrations

Without a version comment on the oban_jobs table, it will rerun all of the migrations. This can happen when comments are stripped when restoring from a backup, most commonly during a transition from one database to another.

The fix is to set the latest migrated version as a comment. To start, search through your previous migrations and find the last time you ran an Oban migration. Once you've found the latest version, e.g. version: 10, then you can set that as a comment on the oban_jobs table:

COMMENT ON TABLE public.oban_jobs IS '10'"

Once the comment is in place only the migrations from that version onward will run.

Heroku

Elixir and Erlang Versions

If your app crashes on launch, be sure to confirm you are running the correct version of Elixir and Erlang (view requirements). If using the hashnuke/elixir buildpack, you can update the elixir_buildpack.config file in your application's root directory to something like:

# Elixir version
elixir_version=1.13.0

# Erlang version
erlang_version=24.2

Available Erlang versions are available here.

Database Connections

Make sure that you have enough available database connections when running on Heroku. Oban uses a database connection in order to listen for Pub/Sub notifications. This is in addition to your Ecto Repo pool_size setting.

Heroku's Hobby tier Postgres plans have a maximum of 20 connections, so if you're using one of those plan accordingly.