elsa-workflows/elsa-core · error · InvalidOperationException

Runtime entity instance

Error message

Runtime entity instance '{instance.Id}' is missing required field '{missingField.Name}'.

What it means

ValidateInstance checks a runtime entity instance against its definition: every field marked IsRequired must have a key present in instance.Data (case-insensitive comparison). Missing required data means the instance cannot be persisted completely, so it throws InvalidOperationException.

Solutions

1. Populate every required field in instance.Data before validating/saving.
2. Temporarily mark the field IsRequired = false in the definition if it is genuinely optional.
3. When loading legacy data, backfill missing required fields during migration or a read-time default step.

Example fix

// before
var instance = new RuntimeEntityInstance { Id = id, Data = { ["Name"] = name } }; // OccurredAt is required
// after
var instance = new RuntimeEntityInstance { Id = id, Data = { ["Name"] = name, ["OccurredAt"] = DateTimeOffset.UtcNow } };

var dataKeys = instance.Data.Keys.ToHashSet(StringComparer.OrdinalIgnoreCase);
var missing = definition.Fields.Where(f => f.IsRequired && !dataKeys.Contains(f.Name)).ToList();
if (missing.Count > 0) throw new InvalidOperationException($"Instance '{instance.Id}' missing required fields: {string.Join(", ", missing.Select(m => m.Name))}");

try { validator.ValidateInstance(definition, instance); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Invalid instance {Id}", instance.Id); throw; }

When it happens

Trigger: Calling ValidateInstance where at least one required definition field has no corresponding key in the instance's Data dictionary.

Common situations: Producing instances from producers that omit fields when values are null; schema evolved to add a required field while older producers still emit instances without it; deserialization dropping null-valued properties.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

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

Appendix: source

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

        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)