elsa-workflows/elsa-core · error · ArgumentOutOfRangeException

Schema version must be greater than zero.

Error message

Schema version must be greater than zero.

What it means

PersistenceSchemaBuilder.Version rejects any schema version less than 1. The builder starts at version 1, and explicit versions must be positive integers because schema versions are used for migration ordering and must be comparable and nonzero.

Solutions

1. Pass an integer >= 1, e.g. builder.Version(1).
2. Validate/normalize the version source (config value) before calling Version.
3. Clamp with Math.Max(1, candidateVersion) when the value is computed.

Example fix

// before
builder.Version(0);
// after
builder.Version(1);

if (version < 1) throw new ArgumentOutOfRangeException(nameof(version));
builder.Version(version);

try { builder.Version(version); }
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "version") { builder.Version(1); }

When it happens

Trigger: Calling PersistenceSchemaBuilder.Version(0) or Version(negative number) while constructing a schema, often computing the version from a variable that defaults to 0 or from an uninitialized config value.

Common situations: Reading the schema version from an unset appsetting or environment variable; off-by-one arithmetic producing 0; passing a default(int) placeholder.

Related errors

• BpmnErrorCodes.ExportSourceVersionUnknown
• Capacity must be greater than zero.
• Unrecognized FluidValue
• This filter only works on objects of type
• Storage unit ' ' is not declared in the persistence schema.

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/de2acd44ef7e069c. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.Persistence.VNext/Builders/PersistenceSchemaBuilder.cs:12

namespace Elsa.Persistence.VNext.Builders;

public class PersistenceSchemaBuilder(string name)
{
    private readonly List<PersistenceTable> _tables = [];
    private readonly List<PersistenceStorageUnit> _storageUnits = [];
    private int _version = 1;

    public PersistenceSchemaBuilder Version(int version)
    {
        if (version < 1)
            throw new ArgumentOutOfRangeException(nameof(version), version, "Schema version must be greater than zero.");

        _version = version;
        return this;
    }

    public PersistenceSchemaBuilder Table(string name, Action<PersistenceTableBuilder> configure, string? schema = null)
    {
        var builder = new PersistenceTableBuilder(name, schema);
        configure(builder);
        _tables.Add(builder.Build());
        return this;
    }

    public PersistenceSchemaBuilder StorageUnit(string name, Action<PersistenceStorageUnitBuilder> configure, string? @namespace = null)
    {
        var builder = new PersistenceStorageUnitBuilder(name, @namespace);
        configure(builder);
        _storageUnits.Add(builder.Build());

View on GitHub (pinned to fe9217bdfa)