elsa-workflows/elsa-core · error · InvalidOperationException

Runtime entity definition name is required.

Error message

Runtime entity definition name is required.

What it means

RuntimeEntityDefinitionValidator.Validate enforces that every runtime entity definition has a non-empty Name. The name is used to resolve the entity's persistence schema, so an unnamed definition cannot be validated further or mapped to storage.

Solutions

  1. Set definition.Name to a stable, non-empty identifier before calling Validate.
  2. If the name comes from options/configuration, verify the config section is bound and the key exists.
  3. Check the construction/builder path to ensure the name is a required parameter rather than an optional property.

Example fix

// before
var def = new RuntimeEntityDefinition { Fields = { ... } };
validator.Validate(def);
// after
var def = new RuntimeEntityDefinition { Name = "AuditEvents", Fields = { ... } };
validator.Validate(def);
Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(definition.Name)) throw new InvalidOperationException("Runtime entity definition must have a Name.");

Try / catch

try { validator.Validate(definition); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Invalid runtime entity definition"); throw; }

Prevention

When it happens

Trigger: Calling Validate with a RuntimeEntityDefinition whose Name is null, empty, or whitespace — typically a definition constructed programmatically or via options where the name was never set.

Common situations: Missing configuration entry that feeds the definition name; a builder used without calling a required WithName/Name setter; diagnostics registering definitions before configuration binding.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/modules/Elsa.Persistence.VNext.Runtime/Services/RuntimeEntityDefinitionValidator.cs:11

using Elsa.Persistence.VNext.Runtime.Models;
using Microsoft.Extensions.Options;

namespace Elsa.Persistence.VNext.Runtime.Services;

public class RuntimeEntityDefinitionValidator(IOptions<RuntimeEntityOptions> options)
{
    public void Validate(RuntimeEntityDefinition definition)
    {
        if (string.IsNullOrWhiteSpace(definition.Name))
            throw new InvalidOperationException("Runtime entity definition name is required.");

        if (definition.Fields.Count == 0)
            throw new InvalidOperationException($"Runtime entity definition '{definition.Name}' must declare at least one field.");

        var duplicateField = definition.Fields.GroupBy(x => x.Name, StringComparer.OrdinalIgnoreCase).FirstOrDefault(x => x.Count() > 1);
        if (duplicateField is not null)
            throw new InvalidOperationException($"Runtime entity definition '{definition.Name}' declares field '{duplicateField.Key}' more than once.");

        var maxIndexedFields = Math.Min(options.Value.MaxIndexedFields, RuntimeEntityPersistenceSchemaProvider.IndexedFieldSlotCount);
        if (definition.Indexes.Count > maxIndexedFields)
            throw new InvalidOperationException($"Runtime entity definition '{definition.Name}' declares {definition.Indexes.Count} indexes, but only {maxIndexedFields} runtime index slots are available.");

        var fields = definition.Fields.Select(x => x.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
        foreach (var index in definition.Indexes)
        {
            if (!fields.Contains(index.FieldName))
                throw new InvalidOperationException($"Runtime entity definition '{definition.Name}' index '{index.Name}' references unknown field '{index.FieldName}'.");
        }

View on GitHub (pinned to fe9217bdfa)