If you are building a Blazor application and need to serve static HTML files directly (like a design system, documentation, or legacy pages), you probably tossed them straight into your wwwroot folder.
Everything works beautifully in your production environment. But when you hit F5 to test locally, you are greeted with a nasty System.IO.InvalidDataException crash in your Kestrel server logs:
The Root Cause: Local Browser Refresh Tooling
At first this looked strange, because I was not using any custom compression code. The problem turned out to be related to the development-time BrowserLink / Browser Refresh pipeline in ASP.NET Core, not the HTML file itself.
This error is not a bug in my code, nor is it an issue with the HTML files. It is caused by a known development-time bug in ASP.NET Core's Hot Reload / Browser Refresh middleware.
When you run your project locally, Visual Studio (version 2026) or the dotnet watch CLI dynamically injects a tiny JavaScript snippet into your HTML responses. This script allows your browser to automatically refresh when you save changes in your code.
However, when you directly request a static .html file from wwwroot in development, the BrowserRefreshMiddleware attempts to read the underlying data stream to inject its script. If the framework compresses or buffers this static stream under certain local configurations, the middleware misinterprets the compression headers, corrupts the stream, and crashes Kestrel.
In .NET 10, static assets can be processed through the SDK's static web assets pipeline. In development, BrowserLink tries to inject its refresh script into HTML responses. That is usually fine for normal HTML, but if the response is being served through the compressed static asset path, the browser refresh middleware can fail while trying to rewrite it.
That is why the issue appeared only for HTML files and not for images like:
https://localhost:7075/assets/logo/blazor.png
Images do not get HTML script injection, so they do not hit the same BrowserLink path.
Why does it work in Production?
This issue completely vanishes in production because Hot Reload and Browser Refresh tools are entirely stripped out when your app runs outside of the Development environment.
How to Fix It
Since the problem lies entirely within local development tooling, you can fix it by telling ASP.NET Core to skip loading the browser tools for your debugging profile.
Solution 1: Update launchSettings.json (Recommended)
The cleanest fix is to append an environment variable to your local launch profile. This fixes the issue for anyone pulling down your repository without breaking their global IDE settings.
- Open your project's Properties/launchSettings.json file.
- Locate the profile you use to run the application (e.g.,
"https"or"http"). - Under the
"environmentVariables"object, add"ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES": "Microsoft.WebTools.BrowserLink.Net".
Your configuration file should look like this:
Solution 2: Disable via Visual Studio Settings
If you prefer a global fix across your IDE without altering your source control files, you can turn off the features directly inside Visual Studio:
- Click the dropdown arrow next to the Hot Reload button (the fire icon 🔥) in the top toolbar and uncheck Enable Hot Reload on File Save.
- Click the dropdown arrow next to the Browser Link icon in the toolbar and uncheck Enable Browser Link.
Other quick fixes or debugging (use wisely in Production env):
- Clear browser cache and rebuild
- Close the browser entirely.
- Delete bin/ and obj/ folders locally.
- In Visual Studio: Build → Clean Solution, then Build → Build Solution.
-
Run the app fresh (F5).
- Disable gzip compression for static files temporarily (test if it's the culprit)
- Open Program.cs.
- Look for lines with .UseResponseCompression() or gzip middleware.
- Temporarily comment them out or add a condition to skip .html files.
-
Rebuild and test.
- Added this to [YOUR_PROJECT.csproj]:
-
<DisableBuildCompression>true</DisableBuildCompression>
or
<DisableBuildCompression Condition="'$(Configuration)' == 'Debug'">true</DisableBuildCompression>
Summary
When serving raw HTML assets straight out of wwwroot, local stream manipulation by .NET's developer tools can accidentally break payload compression. By excluding BrowserLink.Net from your development startup assemblies, you bypass the buggy middleware entirely, making your local development environment behave exactly like your stable production server.
