elsa-workflows/elsa-core · error · InvalidOperationException

Elsa Platform worker ID is required when Platform…

Error message

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

What it means

The Platform integration requires a WorkerId that identifies this runtime worker instance to the Elsa Platform. Validate() throws when WorkerId is null, empty, or whitespace while integration is enabled. The worker ID is sent as a header on command polls and artifact downloads.

Solutions

Set WorkerId to a stable unique value, e.g. Environment.MachineName or a GUID persisted per instance.
Bind WorkerId from configuration/environment (e.g. Elsa:PlatformIntegration:WorkerId).
Disable Platform integration if the runtime should not register as a worker.

Example fix

// before
options.Enabled = true;
// after
options.Enabled = true;
options.WorkerId = $"worker-{Environment.MachineName}-{Environment.ProcessId}";

Defensive patterns

Strategy: validation

Validate before calling

if (options.Enabled && string.IsNullOrWhiteSpace(options.WorkerId))
    options.WorkerId = $"worker-{Environment.MachineName}-{Guid.NewGuid():N}";

Try / catch

try { options.Validate(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("worker ID"))
{
    logger.LogError(ex, "WorkerId must be set for Platform integration.");
}

Prevention

Generate a stable per-instance worker ID at first startup and persist it.
Validate options with ValidateOnStart so missing IDs fail deployment, not runtime.
Ensure each scaled-out instance gets a distinct WorkerId.

When it happens

Trigger: Enabled = true plus Validate() with WorkerId not set (null/empty/whitespace).

Common situations: Forgot to assign a worker identifier when wiring options in code; configuration section missing the WorkerId key; running multiple workers and assuming an ID would be auto-generated (it is not).

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

Appendix: source

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

    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)