{"record":{"id":"94b2ef95232318b6","repo":"elsa-workflows/elsa-core","slug":"workflow-definition-definitionid-does-not-exist-so-its-bpmn","errorCode":null,"errorMessage":"Workflow definition '{definitionId}' does not exist, so its BPMN document cannot be edited.","messagePattern":"Workflow definition '(.+?)' does not exist, so its BPMN document cannot be edited\\.","errorType":"exception","errorClass":"BpmnDefinitionNotFoundException","httpStatus":404,"severity":"error","filePath":"src/modules/Elsa.Bpmn.Interchange/Services/BpmnInterchangeDocumentService.cs","lineNumber":334,"sourceCode":"    /// when If-Match and the loaded snapshot (id, version, graph, name, description, IsLatest) are\n    /// still the row the draft was built from — so a metadata-only save in the window is 412, not a\n    /// silent overwrite. A lost race is <see cref=\"BpmnDocumentPreconditionFailedException\"/>.\n    /// </summary>\n    private async Task<BpmnDocumentImportResult> PersistDocumentEditAsync(\n        string xml,\n        string definitionId,\n        BpmnProcess process,\n        BpmnProcessDefinition rootDefinition,\n        BpmnImportAnalysis analysis,\n        string? expectedETag,\n        CancellationToken cancellationToken)\n    {\n        var filter = WorkflowDefinitionHandle.ByDefinitionId(definitionId, VersionOptions.Latest).ToFilter();\n        var current = await store.FindAsync(filter, cancellationToken);\n\n        if (current is null)\n        {\n            throw new BpmnDefinitionNotFoundException(\n                $\"Workflow definition '{definitionId}' does not exist, so its BPMN document cannot be edited.\");\n        }\n\n        if (expectedETag is not null && !string.Equals(BpmnDocumentETag.From(current), expectedETag, StringComparison.Ordinal))\n        {\n            throw new BpmnDocumentPreconditionFailedException(\n                \"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.\");\n        }\n\n        var expectedId = current.Id;\n        var expectedVersion = current.Version;\n        var expectedName = current.Name;\n        var expectedDescription = current.Description;\n        var expectedStringData = current.StringData;\n\n        var draft = ApplyDocumentEdit(current, process, xml, rootDefinition);\n        await mediator.SendAsync(new WorkflowDefinitionDraftSaving(draft), cancellationToken);\n","sourceCodeStart":316,"sourceCodeEnd":352,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Bpmn.Interchange/Services/BpmnInterchangeDocumentService.cs#L316-L352","documentation":"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.","triggerScenarios":"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)).","commonSituations":"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.","solutions":["Verify the definitionId exists by fetching the workflow definition via the definitions API before PUTting the BPMN document","Create/import the workflow definition first, then edit its BPMN document using the definitionId returned at creation","Check you are pointed at the correct database/tenant where the definition exists"],"exampleFix":"// before\nawait client.PutAsync($\"/bpmn/documents/{nonexistentId}\", content);\n// after\nvar definitions = await client.GetWorkflowDefinitions();\nif (!definitions.Any(d => d.DefinitionId == id))\n    throw new InvalidOperationException($\"Definition {id} not found; create it before editing its BPMN document.\");\nawait client.PutAsync($\"/bpmn/documents/{id}\", content);","handlingStrategy":"try-catch","validationCode":"var filter = WorkflowDefinitionHandle.ByDefinitionId(definitionId, VersionOptions.Latest).ToFilter();\nvar exists = await definitionStore.FindAsync(filter, ct) is not null;\nif (!exists) throw new InvalidOperationException($\"{definitionId} does not exist\");","typeGuard":null,"tryCatchPattern":"try { await service.ImportAsync(definitionId, document); }\ncatch (BpmnDefinitionNotFoundException ex) { log.Warn(ex, \"Definition missing; create it first\"); }","preventionTips":["Fetch the definition via the definitions API before editing its BPMN document","Use the definitionId returned by the creation/import call, never a hand-typed value","Confirm environment/tenant before importing"],"tags":["bpmn","not-found","workflow-definition"],"backgroundTag":"resource-not-found","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}