elsa-workflows/elsa-core · error · InvalidOperationException

A workflow definition or artifact-relative path is required.

Error message

A workflow definition or artifact-relative path is required.

What it means

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.

Solutions

1. Set step.Path to the artifact-relative workflow file path.
2. Or set step.WorkflowDefinition to a JSON object containing the workflow definition (e.g. parsed from an export).
3. If WorkflowDefinition is populated at runtime, verify the variable actually holds a JSON object, not a string or null.
4. Guard the recipe: validate required step inputs before execution and fail early with a clearer message.

Example fix

// before
var step = new ImportWorkflowDefinitionStep(); // neither Path nor WorkflowDefinition set
// after
var step = new ImportWorkflowDefinitionStep { Path = "workflows/main.json" };

var hasSource = !string.IsNullOrWhiteSpace(step.Path)
    || (step.WorkflowDefinition.ValueKind == System.Text.Json.JsonValueKind.Object);
if (!hasSource) throw new InvalidOperationException("Set Path or WorkflowDefinition before import.");

static bool HasWorkflowSource(ImportWorkflowDefinitionStep s) =>
    !string.IsNullOrWhiteSpace(s.Path) ||
    s.WorkflowDefinition.ValueKind == System.Text.Json.JsonValueKind.Object;

try
{
    await step.ExecuteAsync(context);
}
catch (InvalidOperationException ex) when (ex.Message == "A workflow definition or artifact-relative path is required.")
{
    logger.LogError("ImportWorkflowDefinitionStep is not configured: set Path or WorkflowDefinition.");
}

When it happens

Trigger: Executing ImportWorkflowDefinitionStep without setting Path and with WorkflowDefinition left as default (Undefined/Null) or set to a non-object (array, string, number).

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• A configuration key is required.
• A configured default role no longer exists.
• A user creation proposal is required for an unlinked…
• Adapter ' ' does not provide a settings migration from…
• Adapter ' ' has an invalid settings migration from version…

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

Appendix: source

Thrown at src/modules/Elsa.Platform.Integration/Steps/ImportWorkflowDefinitionStep.cs:95

        }

        context.Log($"Workflow definition '{model.DefinitionId}' was imported.");
    }

    private string ResolveWorkflowJson()
    {
        if (!string.IsNullOrWhiteSpace(Path))
        {
            if (artifact.TryGetText(Path, out var content))
                return content;

            throw new InvalidOperationException($"Workflow definition file '{Path}' was not found in the recipe artifact.");
        }

        if (WorkflowDefinition.ValueKind == JsonValueKind.Object)
            return WorkflowDefinition.GetRawText();

        throw new InvalidOperationException("A workflow definition or artifact-relative path is required.");
    }
}

View on GitHub (pinned to fe9217bdfa)