abpframework/abp · error · ArgumentException

Job names cannot be empty when the filter mode is Include or

Error message

Job names cannot be empty when the filter mode is Include or Exclude.

What it means

Thrown by the BackgroundJobNameFilter constructor when mode is Include or Exclude but the jobNames list is empty after filtering out whitespace/null entries. Include/Exclude need at least one name to be meaningful, so an empty list is rejected as a programmer error.

Source

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

    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)
    {
        return new BackgroundJobNameFilter(BackgroundJobNameFilterMode.Exclude, jobNames);
    }

    /// <summary>
    /// Whether the given job name passes this filter, using an ordinal (case-sensitive) comparison for the

View on GitHub (pinned to 7ed43b1931)

Solutions

1. Ensure at least one non-whitespace job name is supplied for Include/Exclude filters.
2. If you genuinely want 'all jobs', use BackgroundJobNameFilterMode.None (or the None property) instead.
3. Validate that the names source is non-empty before constructing the filter.
4. Use the static Include(...) / Exclude(...) factories and guard against empty input.

Example fix

// before
var f = new BackgroundJobNameFilter(BackgroundJobNameFilterMode.Include, names); // names empty -> throws
// after
var f = names.Count == 0
    ? BackgroundJobNameFilter.None
    : BackgroundJobNameFilter.Include(names);

var clean = names?.Where(n => !n.IsNullOrWhiteSpace()).ToList() ?? new();
if (mode != BackgroundJobNameFilterMode.None && clean.Count == 0)
{
    /* use None, or ensure at least one name before constructing */
}

null

try { var f = new BackgroundJobNameFilter(mode, names); }
catch (ArgumentException ex) when (ex.Message.Contains("cannot be empty when the filter mode is Include or Exclude"))
{ /* fall back to None, or populate names */ }

When it happens

Trigger: Constructing new BackgroundJobNameFilter(BackgroundJobNameFilterMode.Include, new List<string>()) or passing only whitespace/null entries with mode Include or Exclude.

Common situations: Building a filter from a query/result that returned zero job names; passing a list before it was populated; deserialization that yielded empty names but a non-None mode; leftover default empty list.

Related errors

• Job names must be empty when the filter mode is None.
• 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/3bde2bd976a6cadd. Report an issue: GitHub.