elsa-workflows/elsa-core · error · InvalidOperationException

Workflow definition file

Error message

Workflow definition file '{Path}' was not found in the recipe artifact.

What it means

ResolveWorkflowJson locates the workflow definition JSON either from an explicit artifact-relative Path or from the WorkflowDefinition property. When Path is set but no such entry exists in the recipe artifact (TryGetText returns false), the step throws this InvalidOperationException naming the missing path.

Solutions

List the artifact's entries (e.g. via artifact inspection APIs) and set Path to an exact existing entry, matching case and separators.
Fix the packaging step so the workflow definition file is actually included in the recipe artifact.
Remove any leading '/' or './' from Path and use the artifact-relative path as stored in the artifact.
Alternatively, drop Path and supply the workflow JSON inline via the WorkflowDefinition property.

Example fix

// before
step.Path = "workflows/order-flow.json"; // artifact contains "workflows/OrderFlow.json"
// after
step.Path = "workflows/OrderFlow.json";

Defensive patterns

Strategy: validation

Validate before calling

if (!artifact.Entries.Any(e => string.Equals(e.Path, step.Path, StringComparison.OrdinalIgnoreCase)))
    throw new InvalidOperationException($"Artifact does not contain '{step.Path}'. Available: {string.Join(", ", artifact.Entries.Select(e => e.Path))}");

Try / catch

try
{
    await step.ExecuteAsync(context);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("was not found in the recipe artifact"))
{
    logger.LogError(ex, "Check the step Path against the artifact contents.");
    throw;
}

Prevention

List artifact entries and log them when packaging recipes.
Keep workflow file names and step Path values in sync (single source of truth).
Avoid casing/separator drift: store paths normalized.

When it happens

Trigger: Executing the import step with Path set to a file name/folder that does not exist inside the recipe artifact — wrong casing, wrong extension, missing directory prefix, or the artifact was built without that file.

Common situations: Renaming workflow files in the recipe source without updating the step's Path; packaging scripts that skip the workflow directory; path separators or leading slashes that don't match how the artifact stores entry names.

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

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

Appendix: source

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

        }, cancellationToken);

        if (!importResult.Succeeded)
        {
            var errors = string.Join("; ", importResult.ValidationErrors.Select(x => x.Message));
            throw new InvalidOperationException($"Workflow definition validation failed: {errors}");
        }

        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)