abpframework/abp · critical · AbpException

No background job is registered for the args type '{argsType

Error message

No background job is registered for the args type '{argsType.FullName}' configured via AddDedicatedWorker. Register the job before configuring a dedicated worker for it.

What it means

Thrown during StartAsync when a dedicated worker is configured for an args type that has no registered background job. The manager calls JobOptions.GetJob(argsType) to resolve the job name; if no job is registered for that type, GetJob throws an AbpException that this block wraps with a clearer message telling you to register the job first. This prevents a dedicated worker from being started for a job that can never be enqueued or executed.

Source

Thrown at framework/src/Volo.Abp.BackgroundJobs/Volo/Abp/BackgroundJobs/BackgroundJobWorkerManager.cs:106

        foreach (var dedicatedWorker in dedicatedWorkers)
        {
            await StartWorkerAsync(dedicatedWorker.LockName, BackgroundJobNameFilter.Include(dedicatedWorker.JobNames), cancellationToken);
        }

        // Default worker processes every job that is not handled by a dedicated worker.
        await StartWorkerAsync(null, BackgroundJobNameFilter.Exclude(allDedicatedJobNames), cancellationToken);
    }

    protected virtual string GetJobName(Type argsType)
    {
        try
        {
            return JobOptions.GetJob(argsType).JobName;
        }
        catch (AbpException ex)
        {
            throw new AbpException(
                $"No background job is registered for the args type '{argsType.FullName}' configured via AddDedicatedWorker. " +
                $"Register the job before configuring a dedicated worker for it.", ex);
        }
    }

    protected virtual async Task StartWorkerAsync(
        string? distributedLockName = null,
        BackgroundJobNameFilter? jobNameFilter = null,
        CancellationToken cancellationToken = default)
    {
        var worker = ServiceProvider.GetRequiredService<IBackgroundJobWorker>();
        await worker.StartAsync(distributedLockName, jobNameFilter, cancellationToken);
        Workers.Add(worker);
    }

    public virtual async Task StopAsync(CancellationToken cancellationToken = default)
    {
        foreach (var worker in Workers)

View on GitHub (pinned to 7ed43b1931)

Solutions

Register the job before configuring the dedicated worker: Configure<AbpBackgroundJobOptions>(o => o.AddJob<UnregisteredJobArgs>()) in the same or an earlier-executing module.
Check module dependency order — ensure the module that calls AddJob is a [DependsOn] dependency of the module that calls AddDedicatedWorker.
Verify the args type name in the error message matches a type you actually registered; correct the type parameter if it is wrong.

Example fix

// before — dedicated worker configured but job never registered
Configure<AbpBackgroundJobWorkerOptions>(o =>
{
    o.AddDedicatedWorker<EmailSendingJobArgs>("email-lock");
});

// after — register the job first
Configure<AbpBackgroundJobOptions>(o => o.AddJob<EmailSendingJobArgs>());
Configure<AbpBackgroundJobWorkerOptions>(o =>
{
    o.AddDedicatedWorker<EmailSendingJobArgs>("email-lock");
});

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the job is registered before adding a dedicated worker.
var jobOpts = serviceProvider.GetRequiredService<IOptions<AbpBackgroundJobOptions>>().Value;
try { jobOpts.GetJob(typeof(MyJobArgs)); }
catch (AbpException)
{
    throw new InvalidOperationException("Register MyJobArgs via AddJob<MyJobArgs>() before adding a dedicated worker.");
}
options.AddDedicatedWorker<MyJobArgs>("lock");

Try / catch

try { await manager.StartAsync(ct); }
catch (AbpException ex) when (ex.Message.Contains("No background job is registered for the args type"))
{
    logger.LogError(ex, "Dedicated worker configured for an unregistered job; add the missing AddJob registration.");
    throw;
}

Prevention

Register jobs (AddJob<TArgs>) in a base/core module that always runs before the module adding dedicated workers.
Use [DependsOn] to enforce module ordering between job registration and dedicated worker configuration.
Add an integration test that starts the host to catch missing registrations early.

When it happens

Trigger: Calling AddDedicatedWorker<UnregisteredJobArgs>() in ConfigureServices without first registering the job via AbpBackgroundJobOptions.AddJob<UnregisteredJobArgs>() (or the AddJob extension on the jobs options). Registering the dedicated worker in a module that runs before the module that registers the job.

Common situations: Adding a new job args type and configuring a dedicated worker for it but forgetting the AddJob registration. Module ordering: the dedicated worker module initializes before the job registration module. Accidentally referencing the wrong args type (a DTO that is not a registered job).

Related errors

AI-assisted analysis of abpframework/abp@7ed43b1931 (2026-08-13). Data as JSON: /api/errors/8fa91f76e64b1594. Report an issue: GitHub.