elsa-workflows/elsa-core · error · InvalidOperationException

Runtime entity definition

Error message

Runtime entity definition '{definition.Name}' index '{index.Name}' references unknown field '{index.FieldName}'.

What it means

Every index on a runtime entity definition must reference a field declared in that same definition (name match is case-insensitive). Validate throws when an index points at a field that does not exist, since no storage slot exists for it.

Solutions

1. Fix the index's FieldName to exactly match a declared field's name (case-insensitive but otherwise identical).
2. If the field was intentionally removed, delete the corresponding index too.
3. Add the missing field to the definition if the index is actually required.

Example fix

// before
def.Fields.Add(new RuntimeEntityField { Name = "CorrelationId" });
def.Indexes.Add(new RuntimeEntityIndex { Name = "IX_Correlation", FieldName = "CorrelationID" }); // mismatch
// after
def.Indexes.Add(new RuntimeEntityIndex { Name = "IX_Correlation", FieldName = "CorrelationId" });

var fieldNames = definition.Fields.Select(f => f.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
var bad = definition.Indexes.Where(i => !fieldNames.Contains(i.FieldName)).ToList();
if (bad.Count > 0) throw new InvalidOperationException($"Indexes referencing unknown fields: {string.Join(", ", bad.Select(b => b.FieldName))}");

try { validator.Validate(definition); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Index field mismatch in {Name}", definition.Name); throw; }

When it happens

Trigger: Calling Validate where an index's FieldName is not among the definition's field names, ignoring case — usually a typo or a field removed while its index remained.

Common situations: Renaming a field without updating indexes; typo in a config-driven index definition; copying an index block from another entity definition.

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/0875dcca7e45b76c. Report an issue: GitHub.

Appendix: source

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

        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)
    {
        var dataKeys = instance.Data.Keys.ToHashSet(StringComparer.OrdinalIgnoreCase);
        var missingField = definition.Fields.FirstOrDefault(x => x.IsRequired && !dataKeys.Contains(x.Name));
        if (missingField is not null)
            throw new InvalidOperationException($"Runtime entity instance '{instance.Id}' is missing required field '{missingField.Name}'.");
    }
}

View on GitHub (pinned to fe9217bdfa)