abpframework/abp · error · ArgumentException

Period must be greater than 0 when provided. Given value

Error message

Period must be greater than 0 when provided. Given value: {Period.Value}.

What it means

Thrown by DynamicBackgroundWorkerSchedule.Validate when the Period property has a value but that value is zero or negative. A dynamic worker needs a positive interval to schedule work; a non-positive period would cause an immediate infinite loop or no firing. Validate is called by the dynamic worker manager's AddAsync and UpdateScheduleAsync before any work is scheduled.

Solutions

1. Set Period to a positive value in milliseconds (e.g. 60000 for 1 minute).
2. Validate configuration before constructing the schedule and fall back to DynamicBackgroundWorkerSchedule.DefaultPeriod (60000) when the configured value is invalid.
3. If you meant to use cron, leave Period null and set CronExpression instead (and use Hangfire/Quartz).

Example fix

// before — period read from config, may be 0
var period = configuration.GetValue<int>("WorkerPeriod");
await manager.AddAsync("worker",
    new DynamicBackgroundWorkerSchedule { Period = period }, handler);

// after — sanitize the configured value
var period = configuration.GetValue<int>("WorkerPeriod");
if (period <= 0) period = DynamicBackgroundWorkerSchedule.DefaultPeriod;
await manager.AddAsync("worker",
    new DynamicBackgroundWorkerSchedule { Period = period }, handler);

var period = configuration.GetValue<int?>("WorkerPeriod");
if (period.HasValue && period.Value <= 0)
{
    throw new ArgumentOutOfRangeException(nameof(period), "WorkerPeriod must be greater than 0.");
}
var schedule = new DynamicBackgroundWorkerSchedule { Period = period };

static bool IsValidPeriod(int? period) => !period.HasValue || period.Value > 0;

When it happens

Trigger: Constructing a DynamicBackgroundWorkerSchedule with Period = 0 or a negative integer and passing it to IDynamicBackgroundWorkerManager.AddAsync or UpdateScheduleAsync (which call schedule.Validate()). Also thrown if Validate() is called manually.

Common situations: Reading the period from configuration (appsettings/ISettingProvider) where the key is missing and defaults to 0. Computing a period from a difference that evaluates to zero or negative (e.g. a 'run in N minutes' computed from a past timestamp). Accidentally setting Period instead of CronExpression with a small value meant as seconds.

Related errors

• At least one of 'Period' or 'CronExpression' must be set.
• Both 'Period' and 'CronExpression' are not set for
• Cannot convert period
• Cannot access a disposed object.
• Cannot convert period

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

Appendix: source

Thrown at framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/DynamicBackgroundWorkerSchedule.cs:17

using System;

namespace Volo.Abp.BackgroundWorkers;

public class DynamicBackgroundWorkerSchedule
{
    public const int DefaultPeriod = 60000;

    public int? Period { get; set; }

    public string? CronExpression { get; set; }

    public virtual void Validate()
    {
        if (Period.HasValue && Period.Value <= 0)
        {
            throw new ArgumentException(
                $"Period must be greater than 0 when provided. Given value: {Period.Value}.",
                nameof(Period));
        }

        if (Period == null && string.IsNullOrWhiteSpace(CronExpression))
        {
            throw new ArgumentException(
                "At least one of 'Period' or 'CronExpression' must be set.");
        }
    }
}

View on GitHub (pinned to 7ed43b1931)