elsa-workflows/elsa-core · error · InvalidOperationException

Elsa Platform workspace ID is required when Platform…

Error message

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

What it means

When the Platform integration is enabled, Validate requires a non-empty WorkspaceId (Guid != Guid.Empty). The workspace ID identifies which Platform workspace this engine belongs to; an empty Guid is treated as unconfigured and rejected.

Solutions

  1. Set options.WorkspaceId to the Guid of your Elsa Platform workspace.
  2. Ensure configuration binding supplies PlatformIntegration:WorkspaceId before validation runs.
  3. Validate the Guid is non-empty at config load time with a clear startup failure message.

Example fix

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

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try { options.Validate(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("workspace ID is required")) { /* log config gap and abort startup */ }

Prevention

When it happens

Trigger: Calling Validate() with Enabled=true and WorkspaceId left at its default Guid.Empty — not bound from configuration or set programmatically.

Common situations: Missing Workspace:Id section in appsettings; default(Guid) placeholder not replaced; copying config from a template that omits the workspace 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/750c0ed2c9bacca4. Report an issue: GitHub.

Appendix: source

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

    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)