Introduction: Why 'dotnet run' Works While F5 Debugging Fails

If you are building multi-project ASP.NET Core MVC applications in Visual Studio Code, you might have encountered a frustrating scenario: running dotnet run directly from your terminal works seamlessly, but pressing F5 to start the VS Code debugger triggers erratic build errors (like CS0006 or missing libhostpolicy.so) or fails to render custom scaffolded Razor views. This guide breaks down why these discrepancies occur and provides a step-by-step solution to get your debugging environment working identically to the .NET CLI.

Deconstructing the Three Sequential Debugger Errors

When launching the debugger produces different outcomes across consecutive attempts, it usually points to race conditions between CLI tasks, working directory mismatches, and Linux sandboxing issues.

  • Attempt 1 (CS0006: Metadata file not found): This error occurs when VS Code's preLaunchTask attempts to build the project, but intermediate build artifacts (like Model.dll in the obj/ref/ directory) are locked or deleted during incremental builds. If dotnet run was executed in a different context or user environment right before, lingering file locks cause the compiler (CSC) to fail when generating reference assemblies.
  • Attempt 2 (Missing libhostpolicy.so): This runtime error happens when the .NET host cannot locate required runtime libraries. On Linux systems—especially when using containerized or Flatpak installations of VS Code—the execution environment under F5 might not share the same system PATH or DOTNET_ROOT environment variables as your native terminal shell. The application incorrectly attempts to locate runtime binaries inside localized Flatpak runtime paths (e.g., /usr/lib/sdk/dotnet10/lib) rather than your system's installed SDK.
  • Attempt 3 (App runs, but custom views fail to load): By the third attempt, the build cache stabilizes, allowing the app to launch. However, custom Razor views or scaffolded Identity pages fail to render because the debugger launched the executable with an incorrect Current Working Directory (cwd) or missing environment variables (such as ASPNETCORE_ENVIRONMENT=Development).

Why Scaffolded Views and Static Web Assets Fail Under the Debugger

ASP.NET Core relies on Static Web Assets and manifest files (such as .staticwebassets.runtime.json) to resolve scaffolded UI pages and custom Razor assets. When you execute dotnet run inside the project root, the CLI automatically establishes the target project directory as the base content root.

When launching through VS Code's debugger without proper path configurations, the working directory often defaults to the workspace root rather than the web project folder. As a result, ASP.NET Core fails to locate the custom static web asset manifests and falls back to the embedded default views provided by pre-compiled Razor Class Libraries (RCLs).

How to Fix VS Code Debugging Configurations

To align your VS Code debugging experience with dotnet run, you need to properly configure .vscode/launch.json and .vscode/tasks.json to ensure correct working directories, environment variables, and build tasks.

1. Configure launch.json

Ensure your launch.json explicitly defines the cwd (Current Working Directory) pointing to your main Web project folder and explicitly sets the development environment: