elsa-workflows/elsa-core · error · InvalidOperationException

Elsa Platform shell overlay path is required when Platform…

Error message

Elsa Platform shell overlay path is required when Platform integration is enabled.

What it means

ShellOverlayPath points at the JSON file used as the shell configuration overlay for the Platform integration. Validate() requires a non-empty path when integration is enabled; the FileShellConfigurationOverlayStore reads and writes this file.

Solutions

  1. Set ShellOverlayPath to an absolute or app-relative JSON file path, e.g. "shell-overlay.json".
  2. Ensure the configuration key (Elsa:PlatformIntegration:ShellOverlayPath) exists in the deployment environment.
  3. Disable Platform integration if no shell overlay is desired (though it is required when enabled).

Example fix

// before
options.Enabled = true;
// after
options.Enabled = true;
options.ShellOverlayPath = Path.Combine(appEnvironment.ContentRootPath, "shell-overlay.json");
Defensive patterns

Strategy: validation

Validate before calling

if (options.Enabled && string.IsNullOrWhiteSpace(options.ShellOverlayPath))
    options.ShellOverlayPath = Path.Combine(env.ContentRootPath, "shell-overlay.json");

Try / catch

try { options.Validate(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("shell overlay path"))
{
    logger.LogError(ex, "ShellOverlayPath is required when Platform integration is enabled.");
}

Prevention

When it happens

Trigger: Enabled = true plus Validate() with ShellOverlayPath null, empty, or whitespace.

Common situations: Deploying to a new environment where the overlay path setting was never added to configuration; container images lacking the configured path; renaming the config key between versions.

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

Appendix: source

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

        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)