elsa-workflows/elsa-core · error · InvalidOperationException

Elsa Platform engine ID is required when Platform…

Error message

Elsa Platform engine ID is required when Platform integration is enabled.

What it means

Validate also requires a non-empty EngineId when the Platform integration is enabled. The engine ID uniquely identifies this engine instance to the Platform; Guid.Empty means it was never assigned and validation throws.

Solutions

Set options.EngineId to the engine's assigned Guid before validation.
Bind PlatformIntegration:EngineId from configuration and confirm non-empty at startup.
Generate a stable Guid per engine instance if the Platform does not pre-assign one.

Example fix

// before
var options = new ElsaPlatformIntegrationOptions { Enabled = true, PlatformEndpoint = endpoint, WorkspaceId = wsId, EngineSecret = "s", WorkerId = "w" };
options.Validate();
// after
var options = new ElsaPlatformIntegrationOptions { Enabled = true, PlatformEndpoint = endpoint, WorkspaceId = wsId, EngineId = Guid.Parse("..."), EngineSecret = "s", WorkerId = "w" };
options.Validate();

Defensive patterns

Strategy: validation

Validate before calling

if (options.Enabled && options.EngineId == Guid.Empty)
    throw new InvalidOperationException("EngineId must be set when Platform integration is enabled.");

Type guard

bool IsValid(ElsaPlatformIntegrationOptions o) => !o.Enabled || o.EngineId != Guid.Empty;

Try / catch

try { options.Validate(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("engine ID is required")) { /* fix config before engine registration */ }

Prevention

Assign each engine a stable Guid in configuration management.
Run Validate() in a startup health check.
Keep engine identity values in secret/config storage, not code defaults.

When it happens

Trigger: Calling Validate() with Enabled=true and EngineId still Guid.Empty because it was not provided in configuration or code.

Common situations: Omitted Engine:Id in appsettings; template config copied without filling engine identity; registering a second engine without assigning it a distinct ID.

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/7a33043bb0a164ea. Report an issue: GitHub.

Appendix: source

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

    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)