OrchardCMS/OrchardCore · critical · MediaConfigurationException

The wwwroot folder for serving cache media files is missing.

Error message

The wwwroot folder for serving cache media files is missing.

What it means

OrchardCore.Media.AmazonS3 registers IMediaFileStoreCacheFileProvider which serves cached S3 media files from the local wwwroot. At startup (ConfigureServices), if IWebHostEnvironment.WebRootPath is null/whitespace it throws MediaConfigurationException, because there is nowhere to store/serve cached files.

Solutions

1. Ensure a wwwroot folder exists in the application content root before startup.
2. Call builder with explicit UseWebRoot(path) pointing at the real static-asset folder.
3. Re-publish the app including static web assets (dotnet publish includes wwwroot by default).
4. If caching to local disk is not wanted, disable the media cache feature/module registration.

Example fix

// before
var builder = WebApplication.CreateBuilder(args);
// after
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.UseWebRoot(Path.Combine(builder.Environment.ContentRootPath, "wwwroot"));

// Fail fast with a clear message before ConfigureServices runs
if (string.IsNullOrWhiteSpace(env.WebRootPath))
    throw new InvalidOperationException("Set UseWebRoot to a valid wwwroot folder before enabling Amazon S3 media.");

try { builder.Services.AddOrchardCms(); }
catch (MediaConfigurationException ex) when (ex.Message.Contains("wwwroot"))
{ /* fix hosting configuration or create wwwroot, then restart */ }

When it happens

Trigger: Starting a site with the Amazon S3 media feature enabled while the web root is missing — e.g. running with WebRootPath not set because wwwroot does not exist in the content root, or a custom host that disables static web assets.

Common situations: Publishing without the wwwroot folder; console/service hosting where UseWebRoot is misconfigured; trimmed deployments that removed wwwroot; running from a working directory other than the app root.

Related errors

• The wwwroot folder for serving cache media files is missing.
• A feature is missing a mandatory 'Id' property in the Module
• The configured identity column size
• The configured table name separator
• The file extension should start with a dot.

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/ae7e035cbea7b5e8. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore.Modules/OrchardCore.Media.AmazonS3/Startup.cs:73

            }

            _logger.LogError("S3 Media configuration validation failed with errors: {Errors} fallback to local file storage.", stringBuilder);
        }
        else
        {
            if (_logger.IsEnabled(LogLevel.Information))
            {
                _logger.LogInformation(
                    "Starting with S3 Media Configuration. BucketName: {BucketName}; BasePath: {BasePath}", storeOptions.BucketName, storeOptions.BasePath);
            }

            services.AddSingleton<IMediaFileStoreCacheFileProvider>(serviceProvider =>
            {
                var hostingEnvironment = serviceProvider.GetRequiredService<IWebHostEnvironment>();

                if (string.IsNullOrWhiteSpace(hostingEnvironment.WebRootPath))
                {
                    throw new MediaConfigurationException("The wwwroot folder for serving cache media files is missing.");
                }

                var mediaOptions = serviceProvider.GetRequiredService<IOptions<MediaOptions>>().Value;
                var shellSettings = serviceProvider.GetRequiredService<ShellSettings>();
                var logger = serviceProvider.GetRequiredService<ILogger<DefaultMediaFileStoreCacheFileProvider>>();

                var mediaCachePath = GetMediaCachePath(
                    hostingEnvironment, shellSettings, DefaultMediaFileStoreCacheFileProvider.AssetsCachePath);

                if (!Directory.Exists(mediaCachePath))
                {
                    Directory.CreateDirectory(mediaCachePath);
                }

                return new DefaultMediaFileStoreCacheFileProvider(logger, mediaOptions.AssetsRequestPath, mediaCachePath);
            });

            // Replace the default media file provider with the media cache file provider.

View on GitHub (pinned to 4306c0717f)