elsa-workflows/elsa-core · error · BpmnDefinitionNotFoundException

Workflow definition ' ' does not exist, so its BPMN…

Error message

Workflow definition '{definitionId}' does not exist, so its BPMN document cannot be edited.

What it means

BpmnInterchangeDocumentService.PersistDocumentEditAsync refuses to edit the BPMN document of a workflow definition that cannot be found by definitionId (latest version lookup). The service throws BpmnDefinitionNotFoundException before any write occurs. This guards against editing documents for definitions that were deleted or never existed.

Solutions

1. Verify the definitionId exists by fetching the workflow definition via the definitions API before PUTting the BPMN document
2. Create/import the workflow definition first, then edit its BPMN document using the definitionId returned at creation
3. Check you are pointed at the correct database/tenant where the definition exists

Example fix

// before
await client.PutAsync($"/bpmn/documents/{nonexistentId}", content);
// after
var definitions = await client.GetWorkflowDefinitions();
if (!definitions.Any(d => d.DefinitionId == id))
    throw new InvalidOperationException($"Definition {id} not found; create it before editing its BPMN document.");
await client.PutAsync($"/bpmn/documents/{id}", content);

var filter = WorkflowDefinitionHandle.ByDefinitionId(definitionId, VersionOptions.Latest).ToFilter();
var exists = await definitionStore.FindAsync(filter, ct) is not null;
if (!exists) throw new InvalidOperationException($"{definitionId} does not exist");

try { await service.ImportAsync(definitionId, document); }
catch (BpmnDefinitionNotFoundException ex) { log.Warn(ex, "Definition missing; create it first"); }

When it happens

Trigger: Calling ImportCoreAsync/PersistDocumentEditAsync with a definitionId whose latest version is not present in the workflow definition store (store.FindAsync returns null for WorkflowDefinitionHandle.ByDefinitionId(definitionId, VersionOptions.Latest)).

Common situations: PUTting a BPMN document for a definition that was deleted, a typo'd definitionId, importing into an environment/database different from where the definition was created, or a definition existing only as an older/published version while Latest lookup fails.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Could not find workflow definition with ID
• Workflow definition with ID
• AlterationFaultCodes.PlanNotFound
• An < : > element declares no ' ', so there is nothing to…
• An < : > element of the ' ' binding declares no ' '.

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

Appendix: source

Thrown at src/modules/Elsa.Bpmn.Interchange/Services/BpmnInterchangeDocumentService.cs:334

    /// when If-Match and the loaded snapshot (id, version, graph, name, description, IsLatest) are
    /// still the row the draft was built from — so a metadata-only save in the window is 412, not a
    /// silent overwrite. A lost race is <see cref="BpmnDocumentPreconditionFailedException"/>.
    /// </summary>
    private async Task<BpmnDocumentImportResult> PersistDocumentEditAsync(
        string xml,
        string definitionId,
        BpmnProcess process,
        BpmnProcessDefinition rootDefinition,
        BpmnImportAnalysis analysis,
        string? expectedETag,
        CancellationToken cancellationToken)
    {
        var filter = WorkflowDefinitionHandle.ByDefinitionId(definitionId, VersionOptions.Latest).ToFilter();
        var current = await store.FindAsync(filter, cancellationToken);

        if (current is null)
        {
            throw new BpmnDefinitionNotFoundException(
                $"Workflow definition '{definitionId}' does not exist, so its BPMN document cannot be edited.");
        }

        if (expectedETag is not null && !string.Equals(BpmnDocumentETag.From(current), expectedETag, StringComparison.Ordinal))
        {
            throw new BpmnDocumentPreconditionFailedException(
                "The workflow definition has been written since the ETag in If-Match was issued. GET the document again, reapply the edit, and PUT it with the new ETag.");
        }

        var expectedId = current.Id;
        var expectedVersion = current.Version;
        var expectedName = current.Name;
        var expectedDescription = current.Description;
        var expectedStringData = current.StringData;

        var draft = ApplyDocumentEdit(current, process, xml, rootDefinition);
        await mediator.SendAsync(new WorkflowDefinitionDraftSaving(draft), cancellationToken);

View on GitHub (pinned to fe9217bdfa)