{"record":{"id":"93045bb09895730f","repo":"elsa-workflows/elsa-core","slug":"elsa-platform-shell-overlay-path-is-required-when-platform","errorCode":null,"errorMessage":"Elsa Platform shell overlay path is required when Platform integration is enabled.","messagePattern":"Elsa Platform shell overlay path is required when Platform integration is enabled\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Platform.Integration/Options/ElsaPlatformIntegrationOptions.cs","lineNumber":51,"sourceCode":"\n        if (PlatformEndpoint is null)\n            throw new InvalidOperationException(\"Elsa Platform endpoint is required when Platform integration is enabled.\");\n        if (WorkspaceId == Guid.Empty)\n            throw new InvalidOperationException(\"Elsa Platform workspace ID is required when Platform integration is enabled.\");\n        if (EngineId == Guid.Empty)\n            throw new InvalidOperationException(\"Elsa Platform engine ID is required when Platform integration is enabled.\");\n        if (string.IsNullOrWhiteSpace(EngineSecret))\n            throw new InvalidOperationException(\"Elsa Platform engine secret is required when Platform integration is enabled.\");\n        if (string.IsNullOrWhiteSpace(WorkerId))\n            throw new InvalidOperationException(\"Elsa Platform worker ID is required when Platform integration is enabled.\");\n        if (PollInterval <= TimeSpan.Zero)\n            throw new InvalidOperationException(\"Elsa Platform poll interval must be positive.\");\n        if (ClaimLeaseDuration < TimeSpan.FromSeconds(1) || ClaimLeaseDuration.TotalSeconds > int.MaxValue)\n            throw new InvalidOperationException(\"Elsa Platform claim lease duration must be between 1 second and the maximum supported Platform lease.\");\n        if (MaxArtifactBytes <= 0 || MaxArtifactBytes > Array.MaxLength)\n            throw new InvalidOperationException(\"Elsa Platform maximum artifact size must be between 1 byte and the maximum runtime buffer size.\");\n        if (string.IsNullOrWhiteSpace(ShellOverlayPath))\n            throw new InvalidOperationException(\"Elsa Platform shell overlay path is required when Platform integration is enabled.\");\n    }\n}\n","sourceCodeStart":33,"sourceCodeEnd":54,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Platform.Integration/Options/ElsaPlatformIntegrationOptions.cs#L33-L54","documentation":"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.","triggerScenarios":"Enabled = true plus Validate() with ShellOverlayPath null, empty, or whitespace.","commonSituations":"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.","solutions":["Set ShellOverlayPath to an absolute or app-relative JSON file path, e.g. \"shell-overlay.json\".","Ensure the configuration key (Elsa:PlatformIntegration:ShellOverlayPath) exists in the deployment environment.","Disable Platform integration if no shell overlay is desired (though it is required when enabled)."],"exampleFix":"// before\noptions.Enabled = true;\n// after\noptions.Enabled = true;\noptions.ShellOverlayPath = Path.Combine(appEnvironment.ContentRootPath, \"shell-overlay.json\");","handlingStrategy":"validation","validationCode":"if (options.Enabled && string.IsNullOrWhiteSpace(options.ShellOverlayPath))\n    options.ShellOverlayPath = Path.Combine(env.ContentRootPath, \"shell-overlay.json\");","typeGuard":null,"tryCatchPattern":"try { options.Validate(); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"shell overlay path\"))\n{\n    logger.LogError(ex, \"ShellOverlayPath is required when Platform integration is enabled.\");\n}","preventionTips":["Ship a default overlay file with deployments that enable Platform integration.","Use absolute paths derived from IWebHostEnvironment.ContentRootPath.","Verify the path exists and is writable in container/CI environments."],"tags":["configuration","file-path","startup-validation","platform-integration"],"backgroundTag":"missing-required-config-field","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}