Dealing with exceptions

Bad things happen - but JobRunr has everything covered thanks to the RetryFilter!

Bad things happen. Any method can throw different types of exceptions. These exceptions can be caused either by programming errors that require you to re-deploy the application, or transient errors, that can be fixed without additional deployment.

JobRunr handles all exceptions that occur both in internal (belonging to JobRunr itself), and external methods (jobs, filters and so on), so it will not bring down the whole application. All internal exceptions are logged (so, don’t forget to enable logging) and in the worst case, background processing of a job will be stopped after 10 retry attempts with increasing delay modifier.

When JobRunr encounters external exception that occured during the execution of the job, it will automatically try to change the state of the Job to Failed, and you always can find this job in the Dashbord UI (it will not expire unless you delete it explicitly).

Detailed information why a job failed

In the previous paragraph it is mentioned that JobRunr will try to change the state of the Job to failed, because state transition is one of places where job filters can intercept and change the state transition. The RetryFilter class is one of them, that reschedules the failed job to be automatically retried after increasing delay.

This filter is applied globally to all methods and has 10 retry attempts by default. So, your methods will be retried in case of exception automatically, and you receive warning log messages on every failed attempt. If retry attempts exceeded their maximum, the job will stay in the Failed state (with an error log message), and you will be able to retry it manually.


You can off-course configure how many retries JobRunr will do by default.

Default retry policy configuration

    .withJobFilters(new RetryFilter(2))
    .useBackgroundJobServer(new BackgroundJobServer(...))
Jobs will only be retried 2 times instead of 10 times as the default RetryFilter is overriden.

This is also configurable by means of a property setting (default-number-of-retries and retry-back-off-time-seed) if you are using the Spring, Micronaut or Quarkus integration.

Per job

You can configure the amount of retries per job by means of the @Job annotation.

    @Job(name="Job Name", retries=2)
    public void doWorkWithCustomJobFilters() {
        System.out.println("I will only be retried two times ");
The number of retries can also be configured per job by using the @Job annotation on each service method.
    @Job(name="Job Name", retries=2)
    public void run(MyJobRequest myJobRequest) {
        System.out.println("I will only be retried two times ");
This is off course also possible on the run method of a JobRequestHandler.