elsa-workflows/elsa-core · error · InvalidOperationException

Elsa Platform endpoint is required when Platform…

Error message

Elsa Platform endpoint is required when Platform integration is enabled.

What it means

ElsaPlatformIntegrationOptions.Validate enforces that when Enabled is true, a PlatformEndpoint must be configured. Without it the Platform integration client has no server URL to connect to, so the option object considers the configuration invalid and throws immediately.

Solutions

Set options.PlatformEndpoint to a valid absolute URI of the Elsa Platform server.
Provide the endpoint via configuration (appsettings.json / environment variable) before the feature starts.
Set Enabled = false if you do not intend to use Platform integration.

Example fix

// before
var options = new ElsaPlatformIntegrationOptions { Enabled = true, WorkspaceId = guid, EngineId = guid, EngineSecret = "s", WorkerId = "w" };
options.Validate();
// after
var options = new ElsaPlatformIntegrationOptions { Enabled = true, PlatformEndpoint = new Uri("https://platform.example.com"), WorkspaceId = guid, EngineId = guid, EngineSecret = "s", WorkerId = "w" };
options.Validate();

Defensive patterns

Strategy: validation

Validate before calling

if (options.Enabled && options.PlatformEndpoint is null)
    throw new InvalidOperationException("PlatformEndpoint must be set when Platform integration is enabled.");

Type guard

bool IsValid(ElsaPlatformIntegrationOptions o) => !o.Enabled || o.PlatformEndpoint is not null;

Try / catch

try { options.Validate(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("endpoint is required")) { /* surface startup config error */ }

Prevention

Validate options at startup via IValidateOptions so failures surface early.
Bind the endpoint from a required config key with fail-fast semantics.
Document the required keys in the options class.

When it happens

Trigger: Calling Validate() (typically at feature startup) with Enabled = true and PlatformEndpoint left null — e.g. enabling the integration flag without setting the endpoint in appsettings or via the options builder.

Common situations: Setting Enabled=true but forgetting the endpoint URL; endpoint bound from an env var that is unset; config section typo so binding never populates PlatformEndpoint.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/modules/Elsa.Platform.Integration/Options/ElsaPlatformIntegrationOptions.cs:35

    public string WorkerId { get; set; } = $"{Environment.MachineName}:{Environment.ProcessId}";

    public TimeSpan PollInterval { get; set; } = TimeSpan.FromSeconds(5);

    public TimeSpan ClaimLeaseDuration { get; set; } = TimeSpan.FromMinutes(5);

    public long MaxArtifactBytes { get; set; } = 4 * 1024 * 1024;

    public string ShellOverlayPath { get; set; } = "platform-shell-overrides.json";

    public IReadOnlyList<string> Capabilities { get; set; } = ["loom.recipe.apply"];

    public void Validate()
    {
        if (!Enabled)
            return;

        if (PlatformEndpoint is null)
            throw new InvalidOperationException("Elsa Platform endpoint is required when Platform integration is enabled.");
        if (WorkspaceId == Guid.Empty)
            throw new InvalidOperationException("Elsa Platform workspace ID is required when Platform integration is enabled.");
        if (EngineId == Guid.Empty)
            throw new InvalidOperationException("Elsa Platform engine ID is required when Platform integration is enabled.");
        if (string.IsNullOrWhiteSpace(EngineSecret))
            throw new InvalidOperationException("Elsa Platform engine secret is required when Platform integration is enabled.");
        if (string.IsNullOrWhiteSpace(WorkerId))
            throw new InvalidOperationException("Elsa Platform worker ID is required when Platform integration is enabled.");
        if (PollInterval <= TimeSpan.Zero)
            throw new InvalidOperationException("Elsa Platform poll interval must be positive.");
        if (ClaimLeaseDuration < TimeSpan.FromSeconds(1) || ClaimLeaseDuration.TotalSeconds > int.MaxValue)
            throw new InvalidOperationException("Elsa Platform claim lease duration must be between 1 second and the maximum supported Platform lease.");
        if (MaxArtifactBytes <= 0 || MaxArtifactBytes > Array.MaxLength)
            throw new InvalidOperationException("Elsa Platform maximum artifact size must be between 1 byte and the maximum runtime buffer size.");
        if (string.IsNullOrWhiteSpace(ShellOverlayPath))
            throw new InvalidOperationException("Elsa Platform shell overlay path is required when Platform integration is enabled.");
    }
}

View on GitHub (pinned to fe9217bdfa)