{"record":{"id":"40ff42bbf7a4689b","repo":"elsa-workflows/elsa-core","slug":"the-document-declares-definitions-processes-count-processes","errorCode":null,"errorMessage":"The document declares {definitions.Processes.Count} processes ({declared}); specify which one to import.","messagePattern":"The document declares (.+?) processes \\((.+?)\\); specify which one to import\\.","errorType":"exception","errorClass":"BpmnInterchangeException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Bpmn.Interchange/Services/BpmnInterchangeDocumentService.cs","lineNumber":856,"sourceCode":"\n        return xml;\n    }\n\n    private static BpmnProcessDefinition ResolveRootDefinition(BpmnDefinitions definitions, string? processId)\n    {\n        if (!string.IsNullOrWhiteSpace(processId))\n        {\n            // BpmnImportOptions.ProcessId already made the read fail fast if the document does not declare this\n            // process, so finding it here can only fail if that guarantee itself changes.\n            return definitions.Processes.First(process => string.Equals(process.ProcessId, processId, StringComparison.Ordinal));\n        }\n\n        if (definitions.Processes.Count == 1)\n            return definitions.Processes[0];\n\n        var declared = string.Join(\", \", definitions.Processes.Select(process => process.ProcessId));\n\n        throw new BpmnInterchangeException(\n            $\"The document declares {definitions.Processes.Count} processes ({declared}); specify which one to import.\");\n    }\n\n    /// <summary>\n    /// Refuses a document that declares the same element id more than once, naming the duplicated ids.\n    /// </summary>\n    /// <remarks>\n    /// <para>\n    /// BPMN requires every element id to be unique within a document. The library's own reader tolerates a repeat —\n    /// <c>BpmnXmlReader</c> walks the XML's own element tree, so it terminates regardless of what any id says — but\n    /// nothing downstream of it does: this type's own <c>EnsureCapabilitiesSatisfied</c> and <c>BpmnWorkBinder.BindScope</c>\n    /// both find \"the nested processes belonging to this scope\" by matching <see cref=\"BpmnWorkBinding.ProcessId\"/>\n    /// against the scope's own id, and <c>Bpmn.Interchange</c>'s own <c>BpmnXmlWriter</c> does the same by matching\n    /// <see cref=\"BpmnWorkBinding.BindingRef\"/>. A <see cref=\"BpmnWorkBinding.NestedProcess\"/>'s own\n    /// <see cref=\"BpmnProcessDefinition.ProcessId\"/> is always the element id of the subprocess element that opens\n    /// it, so a subprocess nested inside another subprocess that reuses its parent's id makes that lookup find its\n    /// own parent — or itself — again on every step down. Each of those three walks then recurses without ever\n    /// terminating and crashes the process outright: .NET cannot catch a <see cref=\"StackOverflowException\"/>. This","sourceCodeStart":838,"sourceCodeEnd":874,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Bpmn.Interchange/Services/BpmnInterchangeDocumentService.cs#L838-L874","documentation":"BpmnInterchangeDocumentService refuses to import a BPMN document when more than one process is declared at the root and no specific process was selected. BPMN interchange files can contain multiple <process> definitions, so the importer needs an unambiguous target. It throws BpmnInterchangeException naming the declared process ids.","triggerScenarios":"Calling the import/root-definition resolution (ResolveRootDefinition) on a BPMN document whose definitions element declares 0 or 2+ processes, without specifying which process to import (e.g. rootDefinition without a process id selector).","commonSituations":"Exporting a multi-process diagram from a modeling tool (Camunda, Signavio) and importing it wholesale; merging several diagrams into one file; accidentally passing an empty or corrupted definitions file.","solutions":["Specify which process to import by passing its process id to the import API.","If the file should contain one process, split the document so each file declares a single <process>.","Verify the document is not empty/corrupt — 0 declared processes also triggers this throw.","Check the declared ids in the error message and confirm the one you intended exists in the file."],"exampleFix":"// before\nvar definition = await documentService.ImportDocumentAsync(stream);\n// after\nvar definition = await documentService.ImportDocumentAsync(stream, processId: \"OrderProcess\");","handlingStrategy":"validation","validationCode":"var processCount = doc.Definitions?.Processes?.Count ?? 0;\nif (processCount != 1) throw new ArgumentException($\"Document must declare exactly one process (found {processCount}); specify the process id to import.\");","typeGuard":"bool IsSingleProcessDocument(BpmnDefinitions d) => d?.Processes?.Count == 1;","tryCatchPattern":"try { var def = await svc.ImportDocumentAsync(stream, processId); }\ncatch (BpmnInterchangeException ex) { log.LogWarning(ex, \"Ambiguous BPMN document\"); /* prompt user to pick a process */ }","preventionTips":["Always pass an explicit process id when importing documents you do not control.","Validate the number of <process> elements before importing.","Keep one process per BPMN file in your pipelines."],"tags":["bpmn","import","ambiguity"],"backgroundTag":"missing-required-argument","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}