elsa-workflows/elsa-core · error · InvalidOperationException

Elsa Platform engine secret is required when Platform…

Error message

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

What it means

Elsa's Platform integration options validator requires a non-empty EngineSecret when Platform integration is enabled. The secret authenticates this runtime engine to the Elsa Platform when polling for commands and downloading artifacts. Validate() is called during options binding/startup and throws InvalidOperationException on the first failing rule.

Solutions

1. Set EngineSecret in ElsaPlatformIntegrationOptions (or bind it from configuration under the Elsa:PlatformIntegration section).
2. Provide the secret via environment variable or user secrets so it is available in the deployment environment.
3. If Platform integration is not intended, disable it (Enabled = false) so validation is skipped.

Example fix

// before
options.Enabled = true;
options.EngineId = engineId;
// after
options.Enabled = true;
options.EngineId = engineId;
options.EngineSecret = configuration["Elsa:PlatformIntegration:EngineSecret"]!;

var secret = configuration["Elsa:PlatformIntegration:EngineSecret"];
if (string.IsNullOrWhiteSpace(secret))
    throw new InvalidOperationException("Configure Elsa:PlatformIntegration:EngineSecret before enabling Platform integration.");

try { options.Validate(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("engine secret"))
{
    logger.LogError(ex, "Platform integration is enabled but EngineSecret is missing.");
}

When it happens

Trigger: Enabling Platform integration (Enabled = true) and calling ElsaPlatformIntegrationOptions.Validate() while EngineSecret is null, empty, or whitespace.

Common situations: Developers set endpoint, workspace ID, and engine ID from configuration but forget the engine secret; the secret is stored in a user-secrets/vault/keyvault binding that was not configured in the environment; a renamed configuration key (e.g. Elsa:Platform:EngineSecret) no longer binds.

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

• Elsa Platform shell overlay path is required when Platform…
• Elsa Platform worker ID is required when Platform…
• A configuration key is required.
• Configuration connection
• Elsa Platform claim lease duration must be between 1 second…

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

Appendix: source

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

    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)