abpframework/abp · error · ArgumentException

Job names must be empty when the filter mode is None.

Error message

Job names must be empty when the filter mode is None.

What it means

Thrown by the BackgroundJobNameFilter constructor when mode is None (match-everything) but a non-empty jobNames list (after filtering whitespace/null entries) was supplied. None semantically ignores names, so providing any is contradictory and treated as a programmer error.

Source

Thrown at framework/src/Volo.Abp.BackgroundJobs/Volo/Abp/BackgroundJobs/BackgroundJobNameFilter.cs:34

    /// </summary>
    public static BackgroundJobNameFilter None { get; } = new(BackgroundJobNameFilterMode.None);

    public BackgroundJobNameFilterMode Mode { get; }

    public IReadOnlyList<string> JobNames { get; }

    public BackgroundJobNameFilter(BackgroundJobNameFilterMode mode, IReadOnlyList<string>? jobNames = null)
    {
        if (!Enum.IsDefined(typeof(BackgroundJobNameFilterMode), mode))
        {
            throw new ArgumentException($"Invalid background job name filter mode: {mode}", nameof(mode));
        }

        var names = jobNames?.Where(x => !x.IsNullOrWhiteSpace()).Distinct(StringComparer.Ordinal).ToList() ?? new List<string>();

        if (mode == BackgroundJobNameFilterMode.None && names.Count > 0)
        {
            throw new ArgumentException("Job names must be empty when the filter mode is None.", nameof(jobNames));
        }

        if (mode != BackgroundJobNameFilterMode.None && names.Count == 0)
        {
            throw new ArgumentException("Job names cannot be empty when the filter mode is Include or Exclude.", nameof(jobNames));
        }

        Mode = mode;
        JobNames = names.AsReadOnly();
    }

    public static BackgroundJobNameFilter Include(IReadOnlyList<string> jobNames)
    {
        return new BackgroundJobNameFilter(BackgroundJobNameFilterMode.Include, jobNames);
    }

    public static BackgroundJobNameFilter Exclude(IReadOnlyList<string> jobNames)
    {

View on GitHub (pinned to 7ed43b1931)

Solutions

1. When using mode None, pass null or an empty list for jobNames.
2. Switch the mode to Include/Exclude if the names are actually meant to filter.
3. Use the static None property (BackgroundJobNameFilter.None) which is pre-built correctly.
4. Validate the (mode, names) pairing at the call site.

Example fix

// before
var f = new BackgroundJobNameFilter(BackgroundJobNameFilterMode.None, names); // throws
// after
var f = BackgroundJobNameFilter.None; // or new(..., None, null)

if (mode == BackgroundJobNameFilterMode.None && names?.Any(n => !n.IsNullOrWhiteSpace()) == true)
{
    /* clear names or switch mode before constructing */
}

null

try { var f = new BackgroundJobNameFilter(mode, names); }
catch (ArgumentException ex) when (ex.Message.Contains("must be empty when the filter mode is None"))
{ /* pass null/empty for None, or switch to Include/Exclude */ }

When it happens

Trigger: Constructing new BackgroundJobNameFilter(BackgroundJobNameFilterMode.None, new[] { "job1" }) - mode None but names non-empty.

Common situations: Reusing a filter-builder that always passes a name list even when the caller wants None; deserialization that populated names but set mode to None; copy-paste leaving a name list on a None filter.

Related errors

• Job names cannot be empty when the filter mode is Include or
• Background job execution is disabled. This method should not
• The background job args type '{duplicateType.FullName}' is a
• The distributed lock name '{lockName}' is already used by an
• Job args types cannot contain null.

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