elsa-workflows/elsa-core · error · InvalidOperationException

Runtime entity definition

Error message

Runtime entity definition '{definition.Name}' must declare at least one field.

What it means

A runtime entity definition must declare at least one field; a fieldless definition has no storage representation. Validate throws InvalidOperationException for definitions with an empty Fields collection.

Solutions

1. Add at least one Field to the definition before validating.
2. If fields are configured externally, fix the config source so the field list binds and is non-empty.
3. Guard conditional field-adding logic so an all-false branch is treated as a configuration error at construction time.

Example fix

// before
var def = new RuntimeEntityDefinition { Name = "Events" };
validator.Validate(def); // Fields is empty
// after
var def = new RuntimeEntityDefinition { Name = "Events" };
def.Fields.Add(new RuntimeEntityField { Name = "OccurredAt", IsRequired = true });
validator.Validate(def);

if (definition.Fields.Count == 0) throw new InvalidOperationException($"Definition '{definition.Name}' has no fields.");

try { validator.Validate(definition); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Definition {Name} invalid", definition.Name); throw; }

When it happens

Trigger: Calling Validate with a RuntimeEntityDefinition whose Fields list has zero entries — e.g. built without adding fields or with all fields conditionally skipped.

Common situations: Config-driven definitions where the fields section is empty or misnamed so nothing binds; conditional registration code that adds no fields for a given environment; copy-pasted definition skeleton not yet filled in.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Runtime entity definition
• Runtime entity definition
• Runtime entity definition
• Runtime entity definition name is required.
• Runtime entity instance

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

Appendix: source

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

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}'.");
        }
    }

    public void ValidateInstance(RuntimeEntityDefinition definition, RuntimeEntityInstance instance)

View on GitHub (pinned to fe9217bdfa)