elsa-workflows/elsa-core · error · InvalidOperationException

Runtime entity definition

Error message

Runtime entity definition '{name}' was not found.

What it means

PublishAsync loads a previously saved runtime entity definition document by (normalized) name and marks it Published. When no stored definition document exists under that name, the manager throws InvalidOperationException with the requested name. Publishing requires a prior SaveDraftAsync; it is not a create operation.

Solutions

1. Save a draft first with SaveDraftAsync(new RuntimeEntityDefinition { Name = name, ... }) before calling PublishAsync.
2. Verify the exact name via GetDefinitionAsync(name); names are trimmed and lowercased by NormalizeName, so use the normalized form.
3. Check that the configured IDocumentStore points to the database/environment that actually contains the definition.

Example fix

// before
await manager.PublishAsync("Orders");
// after
if (await manager.GetDefinitionAsync("orders") is null)
    await manager.SaveDraftAsync(new RuntimeEntityDefinition { Name = "orders", Version = 1 });
await manager.PublishAsync("orders");

if (await manager.GetDefinitionAsync(name) is null)
    throw new InvalidOperationException($"Definition '{name}' must be saved before publishing.");

try { await manager.PublishAsync(name); }
catch (InvalidOperationException ex) when (ex.Message.Contains("was not found")) { /* provision or report */ }

When it happens

Trigger: Calling PublishAsync(name) where name was never saved via SaveDraftAsync, was saved under a different casing/spelling (names are normalized to trimmed lowercase), or the underlying document store lost the record.

Common situations: Typo or inconsistent casing in the definition name; deploying to a fresh database without migrating definitions; calling publish in a CI pipeline before the draft-save step ran; definition was deleted by another process.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Runtime entity definition
• Runtime entity definition
• No declared index exists for storage unit
• Runtime entity definition
• Runtime entity definition document

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

Appendix: source

Thrown at src/modules/Elsa.Persistence.VNext.Runtime/Services/RuntimeEntityManager.cs:42

        var now = DateTimeOffset.UtcNow;
        definition.CreatedAt = existing?.Definition.CreatedAt ?? definition.CreatedAt;
        definition.UpdatedAt = now;

        await SaveDefinitionAsync(definition, existing?.Document.Version ?? 0, cancellationToken);
        await AppendAuditAsync("RuntimeEntityDefinition", definition.Name, "DraftSaved", $"Draft version {definition.Version} saved.", cancellationToken);
        return definition;
    }

    public async Task<RuntimeEntityDefinition?> GetDefinitionAsync(string name, CancellationToken cancellationToken = default)
    {
        var result = await LoadDefinitionDocumentAsync(name, cancellationToken);
        return result?.Definition;
    }

    public async Task<RuntimeEntityDefinition> PublishAsync(string name, CancellationToken cancellationToken = default)
    {
        var existing = await LoadDefinitionDocumentAsync(name, cancellationToken)
            ?? throw new InvalidOperationException($"Runtime entity definition '{name}' was not found.");

        existing.Definition.Status = RuntimeEntityDefinitionStatus.Published;
        existing.Definition.UpdatedAt = DateTimeOffset.UtcNow;
        validator.Validate(existing.Definition);

        await SaveDefinitionAsync(existing.Definition, existing.Document.Version, cancellationToken);
        await AppendAuditAsync("RuntimeEntityDefinition", existing.Definition.Name, "Published", $"Version {existing.Definition.Version} published.", cancellationToken);
        return existing.Definition;
    }

    public async Task<RuntimeEntityDefinition> RetireAsync(string name, CancellationToken cancellationToken = default)
    {
        var existing = await LoadDefinitionDocumentAsync(name, cancellationToken)
            ?? throw new InvalidOperationException($"Runtime entity definition '{name}' was not found.");

        existing.Definition.Status = RuntimeEntityDefinitionStatus.Retired;
        existing.Definition.UpdatedAt = DateTimeOffset.UtcNow;

View on GitHub (pinned to fe9217bdfa)