elsa-workflows/elsa-core · error · InvalidOperationException

Physicalized index ' ' references undeclared field ' ' on…

Error message

Physicalized index '{index.Name}' references undeclared field '{missingField}' on storage unit '{storageUnit.Name}'.

What it means

After resolving the storage unit, GetStorageUnit validates every index in the physicalization policy: each index field must exist on the declared storage unit. This error means an index named by the policy references a field the storage unit never declared, so physicalizing it would produce an index over a nonexistent column.

Solutions

1. Remove or correct the index field in policy.Indexes to reference a field declared on the storage unit.
2. Add the missing field to the storage unit definition if it is genuinely needed.
3. Sync the policy definition with the current schema after field renames.

Example fix

// before
policy.Indexes.Add(new IndexPhysicalizationPolicy { Name = "IX_Status", Fields = ["Staus"] });
// after
policy.Indexes.Add(new IndexPhysicalizationPolicy { Name = "IX_Status", Fields = ["Status"] });

var unit = schema.StorageUnits.Single(u => u.Name == policy.StorageUnit);
var fieldSet = unit.Fields.Select(f => f.Name).ToHashSet(StringComparer.Ordinal);
var bad = policy.Indexes.SelectMany(i => i.Fields).FirstOrDefault(f => !fieldSet.Contains(f));
if (bad != null) throw new InvalidOperationException($"Index field '{bad}' is not declared on '{unit.Name}'.");

try { GetStorageUnit(schema, policy); }
catch (InvalidOperationException ex) when (ex.Message.Contains("references undeclared field")) { /* correct index fields */ }

When it happens

Trigger: Adding an index to StoragePhysicalizationPolicy.Indexes whose Fields include a name not among storageUnit.Fields — typically after renaming or removing a field, or defining indexes against a unit's old shape.

Common situations: Schema field renamed while physicalization policy still references the old field name; index copied from another storage unit's policy; typo in field name.

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

• Storage unit ' ' was not declared by schema ' '.
• MongoDB physicalization supports dedicated document…
• No declared index exists for storage unit
• Runtime entity definition
• SQLite identifier ' ' is not valid for physicalization.

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

Appendix: source

Thrown at src/modules/Elsa.Persistence.VNext/Physicalization/PhysicalizationPolicyValidator.cs:21

namespace Elsa.Persistence.VNext.Physicalization;

public static class PhysicalizationPolicyValidator
{
    public static PersistenceStorageUnit GetStorageUnit(PersistenceSchema schema, StoragePhysicalizationPolicy policy)
    {
        var storageUnit = schema.StorageUnits.SingleOrDefault(x => x.Name == policy.StorageUnit);

        if (storageUnit == null)
            throw new InvalidOperationException($"Storage unit '{policy.StorageUnit}' was not declared by schema '{schema.Name}'.");

        var fields = storageUnit.Fields.Select(x => x.Name).ToHashSet(StringComparer.Ordinal);

        foreach (var index in policy.Indexes)
        {
            var missingField = index.Fields.FirstOrDefault(field => !fields.Contains(field));

            if (missingField != null)
                throw new InvalidOperationException($"Physicalized index '{index.Name}' references undeclared field '{missingField}' on storage unit '{storageUnit.Name}'.");
        }

        return storageUnit;
    }
}

View on GitHub (pinned to fe9217bdfa)