{"record":{"id":"ae7e035cbea7b5e8","repo":"OrchardCMS/OrchardCore","slug":"the-wwwroot-folder-for-serving-cache-media-files-is-missing","errorCode":null,"errorMessage":"The wwwroot folder for serving cache media files is missing.","messagePattern":"The wwwroot folder for serving cache media files is missing\\.","errorType":"exception","errorClass":"MediaConfigurationException","httpStatus":null,"severity":"critical","filePath":"src/OrchardCore.Modules/OrchardCore.Media.AmazonS3/Startup.cs","lineNumber":73,"sourceCode":"            }\n\n            _logger.LogError(\"S3 Media configuration validation failed with errors: {Errors} fallback to local file storage.\", stringBuilder);\n        }\n        else\n        {\n            if (_logger.IsEnabled(LogLevel.Information))\n            {\n                _logger.LogInformation(\n                    \"Starting with S3 Media Configuration. BucketName: {BucketName}; BasePath: {BasePath}\", storeOptions.BucketName, storeOptions.BasePath);\n            }\n\n            services.AddSingleton<IMediaFileStoreCacheFileProvider>(serviceProvider =>\n            {\n                var hostingEnvironment = serviceProvider.GetRequiredService<IWebHostEnvironment>();\n\n                if (string.IsNullOrWhiteSpace(hostingEnvironment.WebRootPath))\n                {\n                    throw new MediaConfigurationException(\"The wwwroot folder for serving cache media files is missing.\");\n                }\n\n                var mediaOptions = serviceProvider.GetRequiredService<IOptions<MediaOptions>>().Value;\n                var shellSettings = serviceProvider.GetRequiredService<ShellSettings>();\n                var logger = serviceProvider.GetRequiredService<ILogger<DefaultMediaFileStoreCacheFileProvider>>();\n\n                var mediaCachePath = GetMediaCachePath(\n                    hostingEnvironment, shellSettings, DefaultMediaFileStoreCacheFileProvider.AssetsCachePath);\n\n                if (!Directory.Exists(mediaCachePath))\n                {\n                    Directory.CreateDirectory(mediaCachePath);\n                }\n\n                return new DefaultMediaFileStoreCacheFileProvider(logger, mediaOptions.AssetsRequestPath, mediaCachePath);\n            });\n\n            // Replace the default media file provider with the media cache file provider.","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/OrchardCMS/OrchardCore/blob/4306c0717fe573f6fca1b4955909ddab6a192807/src/OrchardCore.Modules/OrchardCore.Media.AmazonS3/Startup.cs#L55-L91","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure a wwwroot folder exists in the application content root before startup.","Call builder with explicit UseWebRoot(path) pointing at the real static-asset folder.","Re-publish the app including static web assets (dotnet publish includes wwwroot by default).","If caching to local disk is not wanted, disable the media cache feature/module registration."],"exampleFix":"// before\nvar builder = WebApplication.CreateBuilder(args);\n// after\nvar builder = WebApplication.CreateBuilder(args);\nbuilder.WebHost.UseWebRoot(Path.Combine(builder.Environment.ContentRootPath, \"wwwroot\"));","handlingStrategy":"try-catch","validationCode":"// Fail fast with a clear message before ConfigureServices runs\nif (string.IsNullOrWhiteSpace(env.WebRootPath))\n    throw new InvalidOperationException(\"Set UseWebRoot to a valid wwwroot folder before enabling Amazon S3 media.\");","typeGuard":null,"tryCatchPattern":"try { builder.Services.AddOrchardCms(); }\ncatch (MediaConfigurationException ex) when (ex.Message.Contains(\"wwwroot\"))\n{ /* fix hosting configuration or create wwwroot, then restart */ }","preventionTips":["Always ship wwwroot with deployments that use file-store caching.","Set UseWebRoot explicitly in nonstandard hosting (services, containers).","Verify dotnet publish output includes static web assets.","Disable local media caching when a web root is intentionally absent."],"tags":["startup","configuration","aws-s3","media","filesystem"],"backgroundTag":"directory-not-found","analyzedSha":"4306c0717fe573f6fca1b4955909ddab6a192807","analyzedAt":"2026-09-13T17:41:05.024Z","contentChangedAt":"2026-09-13T17:41:05.024Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}