elsa-workflows/elsa-core · error · InvalidOperationException

Workflow definition payload is invalid.

Error message

Workflow definition payload is invalid.

What it means

ImportWorkflowDefinitionStep deserializes the resolved workflow JSON into a WorkflowDefinitionModel using the API serializer. If the payload is not well-formed JSON or cannot be deserialized (JsonException, NotSupportedException, InvalidOperationException), the step wraps the failure in this InvalidOperationException to give a single, clear import error while preserving the inner exception.

Solutions

1. Validate the workflow JSON with a JSON parser and compare its structure against a known-good WorkflowDefinitionModel export.
2. Re-export the workflow definition from a compatible Elsa Studio/CLI version so the model schema matches this runtime.
3. Check ResolveWorkflowJson inputs: confirm Path points at the right artifact entry or WorkflowDefinition holds a JSON object, not another file type.
4. Inspect the inner exception (ex.InnerException) for the exact JSON parse error and the offending offset/token.

Example fix

// before
step.WorkflowDefinition = "not-json-at-all";
// after
step.WorkflowDefinition = System.Text.Json.JsonDocument.Parse(File.ReadAllText("workflow.json")).RootElement;

try { using var _ = System.Text.Json.JsonDocument.Parse(workflowJson); }
catch (System.Text.Json.JsonException ex)
{
    throw new InvalidOperationException("Workflow JSON is not valid before import.", ex);
}

static bool IsJsonObject(string json) =>
    System.Text.Json.JsonDocument.Parse(json).RootElement.ValueKind == System.Text.Json.JsonValueKind.Object;

try
{
    await step.ExecuteAsync(context);
}
catch (InvalidOperationException ex) when (ex.Message == "Workflow definition payload is invalid.")
{
    logger.LogError(ex.InnerException, "Deserialization failed: {Reason}", ex.InnerException?.Message);
}

When it happens

Trigger: Executing the import step with malformed JSON, JSON that is not an object matching WorkflowDefinitionModel (e.g. an array or string), or a shape from an incompatible Elsa version whose serializer throws NotSupportedException.

Common situations: Hand-editing a workflow export and breaking JSON syntax; pointing the step at the wrong artifact file (not a workflow definition); exporting from a newer/older Elsa version with a changed model schema.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• The serialization type alias is missing.
• Unsupported console stream value
• The persisted external authentication value could not be…
• The upstream logout mode must be a string.
• The upstream logout mode is not supported.

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

Appendix: source

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

                    $"Workflow definition file '{Path}' was not found in the recipe artifact.",
                    context.Target("input.path"))
            ]);
        }

        return ValueTask.FromResult<IReadOnlyList<RecipeDiagnostic>>([]);
    }

    public async ValueTask ExecuteAsync(StepContext context, CancellationToken cancellationToken = default)
    {
        var workflowJson = ResolveWorkflowJson();
        WorkflowDefinitionModel model;
        try
        {
            model = apiSerializer.Deserialize<WorkflowDefinitionModel>(workflowJson);
        }
        catch (Exception ex) when (ex is JsonException or NotSupportedException or InvalidOperationException)
        {
            throw new InvalidOperationException("Workflow definition payload is invalid.", ex);
        }

        var importResult = await importer.ImportAsync(new SaveWorkflowDefinitionRequest
        {
            Model = model,
            Publish = Publish
        }, 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()

View on GitHub (pinned to fe9217bdfa)