{"record":{"id":"208a967d72887bb9","repo":"elsa-workflows/elsa-core","slug":"a-workflow-definition-or-artifact-relative-path-is-required","errorCode":null,"errorMessage":"A workflow definition or artifact-relative path is required.","messagePattern":"A workflow definition or artifact-relative path is required\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Platform.Integration/Steps/ImportWorkflowDefinitionStep.cs","lineNumber":95,"sourceCode":"        }\n\n        context.Log($\"Workflow definition '{model.DefinitionId}' was imported.\");\n    }\n\n    private string ResolveWorkflowJson()\n    {\n        if (!string.IsNullOrWhiteSpace(Path))\n        {\n            if (artifact.TryGetText(Path, out var content))\n                return content;\n\n            throw new InvalidOperationException($\"Workflow definition file '{Path}' was not found in the recipe artifact.\");\n        }\n\n        if (WorkflowDefinition.ValueKind == JsonValueKind.Object)\n            return WorkflowDefinition.GetRawText();\n\n        throw new InvalidOperationException(\"A workflow definition or artifact-relative path is required.\");\n    }\n}\n","sourceCodeStart":77,"sourceCodeEnd":98,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Platform.Integration/Steps/ImportWorkflowDefinitionStep.cs#L77-L98","documentation":"ResolveWorkflowJson requires exactly one source of workflow JSON: either a non-empty Path pointing into the recipe artifact, or a WorkflowDefinition JSON element containing an object. If neither is supplied (no Path and WorkflowDefinition is not a JSON object), the step throws this InvalidOperationException explaining both options.","triggerScenarios":"Executing ImportWorkflowDefinitionStep without setting Path and with WorkflowDefinition left as default (Undefined/Null) or set to a non-object (array, string, number).","commonSituations":"Recipe authoring mistakes: adding the import step but forgetting to configure it; binding WorkflowDefinition to a variable that resolved to nothing at runtime; copying a step template and deleting the configuration.","solutions":["Set step.Path to the artifact-relative workflow file path.","Or set step.WorkflowDefinition to a JSON object containing the workflow definition (e.g. parsed from an export).","If WorkflowDefinition is populated at runtime, verify the variable actually holds a JSON object, not a string or null.","Guard the recipe: validate required step inputs before execution and fail early with a clearer message."],"exampleFix":"// before\nvar step = new ImportWorkflowDefinitionStep(); // neither Path nor WorkflowDefinition set\n// after\nvar step = new ImportWorkflowDefinitionStep { Path = \"workflows/main.json\" };","handlingStrategy":"type-guard","validationCode":"var hasSource = !string.IsNullOrWhiteSpace(step.Path)\n    || (step.WorkflowDefinition.ValueKind == System.Text.Json.JsonValueKind.Object);\nif (!hasSource) throw new InvalidOperationException(\"Set Path or WorkflowDefinition before import.\");","typeGuard":"static bool HasWorkflowSource(ImportWorkflowDefinitionStep s) =>\n    !string.IsNullOrWhiteSpace(s.Path) ||\n    s.WorkflowDefinition.ValueKind == System.Text.Json.JsonValueKind.Object;","tryCatchPattern":"try\n{\n    await step.ExecuteAsync(context);\n}\ncatch (InvalidOperationException ex) when (ex.Message == \"A workflow definition or artifact-relative path is required.\")\n{\n    logger.LogError(\"ImportWorkflowDefinitionStep is not configured: set Path or WorkflowDefinition.\");\n}","preventionTips":["Validate recipe step configuration at build/authoring time.","Never construct import steps without one of Path/WorkflowDefinition.","Type-check runtime-bound WorkflowDefinition variables to confirm they resolve to JSON objects."],"tags":["missing-argument","workflow-import","configuration"],"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"}