Last Updated:

How to Fix 'Failed to Launch Debug Adapter' Error in Visual Studio 2022 for ASP.NET Core MVC Docker Projects (Target Framework 5.0)

If you’re developing an ASP.NET Core MVC application targeting .NET 5.0 with Docker support in Visual Studio 2022, you may have encountered the frustrating "Failed to Launch Debug Adapter" error when trying to debug. This error typically occurs when Visual Studio cannot establish a connection with the Docker debug adapter, preventing your application from launching in debug mode.

While .NET 5.0 reached end of support on May 10, 2022, many developers still maintain legacy projects targeting this framework. This guide walks you through the root causes of this error and the fixes that resolve it most often—starting with two quick checks that clear a large share of cases.

Quick answer: close Visual Studio, delete %USERPROFILE%\vsdbg and %USERPROFILE%\onecoremsvsmon, restart Docker Desktop, and press F5. If the error persists, work through the causes below in order.

Table of Contents#

  1. Understanding the "Failed to Launch Debug Adapter" Error
  2. Common Causes of the Error
  3. Quick Checks Before You Start
  4. Step-by-Step Solutions
  5. Troubleshooting FAQs
  6. Conclusion
  7. References

Understanding the "Failed to Launch Debug Adapter" Error#

The "Failed to Launch Debug Adapter" error occurs when Visual Studio’s debug adapter (a component that bridges the IDE and the running application) cannot communicate with the Docker container hosting your ASP.NET Core app. This breakdown in communication can stem from misconfigurations, missing dependencies, or environmental issues (e.g., Docker not running, outdated tools, or port conflicts).

When this error appears, Visual Studio may display a message like:

"Failed to launch debug adapter. Additional information may be available in the Output window."

Checking the Output window (under the Container Tools channel, or Docker/Debug in older Visual Studio versions) often reveals clues, such as "Could not connect to the debug adapter" or "Timeout while waiting for container to start."

Common Causes#

Before diving into solutions, let’s identify the most likely culprits:

  • Stale debugger components: A corrupted %USERPROFILE%\vsdbg cache that Visual Studio mounts into the container.
  • Outdated Docker Desktop: Incompatibility between Docker Desktop and Visual Studio 2022.
  • Missing .NET 5.0 SDK or runtime: The target framework (5.0) requires the .NET 5.0 SDK to build and the ASP.NET Core 5.0 runtime to run.
  • Corrupted Docker Launch Settings: Misconfigured launchSettings.json (e.g., invalid ports, missing Docker command names).
  • Stale Build Artifacts: Leftover bin/obj folders or Docker images/containers causing conflicts.
  • Container image missing debugger prerequisites: Minimal or custom images without unzip, curl, or bash can’t install and run vsdbg.
  • Wrong container OS or file sharing disabled: The project targets Linux containers but Docker Desktop is in Windows-container mode, or drive sharing isn’t enabled on a Hyper-V backend.
  • Firewall or antivirus restrictions: Security software blocking Docker from communicating with Visual Studio.
  • Port Conflicts: The application’s configured port is already in use by another process.
  • Visual Studio regression: A bug introduced by a recent VS update. For example, users reported 4294967295 with Docker debugging after the 17.10 update and resolved it by rolling back to 17.9.6.

Quick Checks Before You Start#

These two checks are quick, reversible, and resolve a large share of “Failed to Launch Debug Adapter” cases. Try them before working through the longer list.

Clear Stale Debugger Components#

For Linux containers, Visual Studio copies its managed debugger (vsdbg) into your user profile and mounts it into the container at /remote_debugger. If that cache is stale, partially downloaded, or was created by an older VS version, the adapter cannot start. Microsoft’s Container Tools troubleshooting guidance recommends deleting the cached folders so Visual Studio downloads fresh copies on the next debug session.

  1. Close Visual Studio and stop the project’s containers.
  2. Delete the cached debugger folders. In Command Prompt:
    rmdir /s /q "%USERPROFILE%\vsdbg"
    rmdir /s /q "%USERPROFILE%\onecoremsvsmon"
    Or in PowerShell:
    Remove-Item -Recurse -Force "$env:USERPROFILE\vsdbg" -ErrorAction SilentlyContinue
    Remove-Item -Recurse -Force "$env:USERPROFILE\onecoremsvsmon" -ErrorAction SilentlyContinue
  3. Start Docker Desktop, reopen the solution, and press F5. The first launch is slower because vsdbg is downloaded again.

If the Output window shows /remote_debugger/vsdbg missing, or an error such as ERROR: Command 'unzip' not found, this is very likely your cause (see step 11 for the image-side fix).

Confirm Docker Is Running and the Container OS Matches#

A stopped Docker engine or a Linux/Windows container mismatch produces the same generic adapter error.

  1. Verify the engine is reachable:
    docker version
    If the server section fails, start Docker Desktop and wait for the whale icon to report that the engine is running.
  2. Check which container type Docker is using:
    docker info --format "{{.OSType}}"
    This should print linux for a typical ASP.NET Core 5.0 Linux image. If it prints windows, right-click the Docker tray icon and choose Switch to Linux containers... (or switch your project to a Windows container image).
  3. In Visual Studio, make sure the Docker profile—not IIS Express or the .NET SDK profile—is selected in the debug target dropdown.

Why this works: the debug adapter can only attach to a running container of the type the project expects. A stopped engine or a Windows/Linux mismatch leaves it with nothing to connect to.

Step-by-Step Solutions#

Follow these solutions in order (from simplest to advanced) to resolve the error.

1. Update Docker Desktop#

Docker Desktop updates often include fixes for compatibility with Visual Studio. Ensure you’re running the latest version:

  1. Open Docker Desktop.
  2. Go to Settings > Software updates > Check for updates (or use Check for updates in the Docker menu). You can also download the latest installer from the Docker Desktop download page.
  3. Install the update, restart Docker Desktop, then reboot Windows if the installer asks you to.

Why this works: Older Docker versions can lag behind the debug adapter protocol and WSL integration that Visual Studio 2022 expects.

2. Verify .NET 5.0 SDK Installation#

Since your project targets .NET 5.0, the .NET 5.0 SDK must be installed on your system.

  1. Open Command Prompt or PowerShell.

  2. Run the commands:

    dotnet --list-sdks
    dotnet --list-runtimes
  3. Check that a 5.0.x SDK appears in the first list (the latest is 5.0.408), and that Microsoft.NETCore.App 5.0.x and Microsoft.AspNetCore.App 5.0.x appear in the second list (the latest runtime is 5.0.17).

    • If missing: Download the .NET 5.0 SDK from the Microsoft download archive (select SDK for your OS), then restart Visual Studio so it picks up the new SDK.
    • If installed: Proceed to the next step.

Why this works: Without the 5.0 SDK, Visual Studio cannot build the project; without the ASP.NET Core 5.0 runtime, the container has no matching framework to run against. Both failures surface as adapter connection errors.

Note: .NET 5 reached end of support on May 10, 2022, so the SDK and runtime no longer receive security fixes. Install it only for legacy maintenance, and plan an upgrade (see the FAQ).

3. Inspect Docker Launch Settings#

The launchSettings.json file (located in the Properties folder of your project) defines debug configurations. A misconfigured Docker profile here is a common trigger.

  1. Open Properties/launchSettings.json.

  2. Locate the Docker profile (look for "commandName": "Docker"). It should resemble:

    "Docker": {  
      "commandName": "Docker",  
      "launchBrowser": true,  
      "launchUrl": "{Scheme}://{ServiceHost}:{ServicePort}",  
      "environmentVariables": {  
        "ASPNETCORE_URLS": "https://+:443;http://+:80"  
      },  
      "publishAllPorts": true  
    }  
  3. Verify:

    • commandName is set to "Docker" (not "Project" or "IISExpress"), and the profile name matches the one selected in Visual Studio’s debug dropdown.
    • publishAllPorts is true; this passes -P to docker run, which maps the image’s exposed ports to random host ports. If you need a predictable URL, add httpPort and sslPort instead and update launchUrl to use them.
    • ASPNETCORE_URLS includes valid ports (e.g., https://+:443;http://+:80) and matches the ports exposed in your Dockerfile.
    • The JSON is valid—a trailing comma or a missing brace is enough to make Visual Studio ignore the profile.

Why this works: Incorrect launch settings can prevent the container from exposing ports or launching the app, leaving the debug adapter with no endpoint to connect to. In Visual Studio 2022 you can also edit these values through the launch-profile dropdown > Debug Properties, which avoids JSON syntax errors.

4. Clean and Rebuild the Project#

Stale build artifacts (e.g., in bin/obj folders) can corrupt the Docker image build process.

  1. In Visual Studio, right-click your project > Clean.
  2. Right-click again > Rebuild.
  3. Manually delete the bin and obj folders (optional but thorough):
    • Navigate to your project directory in File Explorer.
    • Delete the bin and obj folders.

Why this works: Rebuilding ensures fresh binaries, and deleting bin/obj clears residual files that may conflict with Docker image creation.

5. Reset Docker State (Containers/Images)#

Corrupted Docker containers or images can block the debug adapter. Resetting Docker’s state often resolves this.

  1. Open PowerShell (Run as Administrator).
  2. Stop all running containers:
    docker stop $(docker ps -q)
    In Command Prompt, the $(...) syntax doesn’t work; use this instead:
    for /f "tokens=*" %i in ('docker ps -q') do docker stop %i
  3. Delete all unused containers, images, and volumes (warning: this clears all Docker data that isn’t currently in use, including build caches and named volumes):
    docker system prune -a --volumes
  4. Restart Docker Desktop, then restart Visual Studio.

Why this works: Stale or corrupted containers and images may fail to start, so the debug adapter has nothing to attach to. Recreating the container also forces Docker to use a fresh image instead of a cached one.

6. Configure Firewall Rules#

Windows Firewall may block Docker from communicating with Visual Studio. Ensure Docker is allowed through the firewall:

  1. Open Windows Defender Firewall > Allow an app through firewall.
  2. Click Change settings > Allow another app....
  3. Click Browse and navigate to:
    • C:\Program Files\Docker\Docker\resources\com.docker.backend.exe
    • C:\Program Files\Docker\Docker\Docker Desktop.exe
  4. Check Private for these executables. Only add Public if you actually use a public network profile on that machine.
  5. Click OK to save.

Why this works: Firewall restrictions can block the debug adapter’s network communication with Docker.

If the Output window points to a network or DNS failure, also try Microsoft’s Cleanup Container Host Networking script, and add exclusions for your project folder and Docker data folder in third-party antivirus tools. On WSL 2, traffic between Windows and the container is local, so opening public firewall ports is rarely the real fix; a VPN or proxy is a more common culprit.

7. Update Visual Studio 2022#

Older versions of Visual Studio 2022 may have bugs affecting Docker debugging. Ensure you’re on the latest update:

  1. Open Visual Studio Installer.
  2. Click Update (if available) next to "Visual Studio 2022".
  3. Restart Visual Studio after the update completes.

Why this works: Microsoft regularly patches Container Tools and debugger issues in VS servicing updates—check the release notes for “Docker” or “Container Tools” fixes.

If the error started immediately after a VS update, updating again may not help. There have been regressions in Docker debugging—for example, users reported error code 4294967295 after the 17.10 update and fixed it by rolling back to 17.9.6. Install the latest patch first; if the problem persists, roll back via Visual Studio Installer > More > Rollback to previous version, or use the Repair option. Visual Studio 2022 remains in mainstream support until January 13, 2027, so staying on a serviced 17.x build is still preferable for legacy .NET 5 work.

8. Reinstall Docker Support in the Project#

If Docker integration files are corrupted, reinstalling Docker support can fix misconfigurations. Back up any hand-edited Dockerfile or docker-compose.yml first—Visual Studio may overwrite them.

  1. Right-click your project in Solution Explorer > Add > Docker Support (called Container Support in newer Visual Studio versions).

  2. Select Linux or Windows (match your Docker Desktop configuration) and click OK.

    • Note: If the option is grayed out, first remove existing Docker support: right-click the project > Remove Docker Support (or Remove Container Support).
  3. Rebuild the project and try debugging again.

Why this works: Reinstalling regenerates the Dockerfile, orchestration files, and launch settings, replacing corrupted integration files with versions Visual Studio knows how to debug.

9. Check for Port Conflicts#

If your app uses a port already occupied by another process (e.g., 443 or 80), the Docker container may fail to start, breaking the debug adapter.

  1. Identify the port your app uses: Check launchSettings.json for ASPNETCORE_URLS (e.g., https://+:443).

  2. Check if the port is in use:

    • Open Command Prompt (Admin) and run:
      netstat -ano | findstr :443
      Replace 443 with your port. In PowerShell, Get-NetTCPConnection -LocalPort 443 shows the same information more readably.
    • Note the PID (Process ID) of the conflicting process.
  3. End the conflicting process:

    • Open Task Manager > Details tab.
    • Find the PID and end the process (right-click > End Task).
  4. Change the host port in launchSettings.json (for example, set "sslPort": 44300) while leaving ASPNETCORE_URLS on the container port (https://+:443). The host port is what conflicts; the container port can stay the same.

Why this works: A blocked host port prevents Docker from starting the container, so the debug adapter has no target to connect to.

10. Enable Debug Logging for Docker#

If all else fails, collect diagnostics before changing more settings.

  1. Reproduce the error and open View > Output. Select Container Tools (or Docker) from the “Show output from” dropdown. Read the last 20–30 lines, which usually name the failing stage: image build, container start, vsdbg mount, or port binding.

  2. Inspect the container itself:

    docker ps -a
    docker logs <container-name-or-id>
    docker inspect <container-name-or-id>
  3. Enable Container Tools diagnostic logs. Visual Studio has no simple “debug logging” checkbox for Docker; instead, set the environment variable that matches your project type before starting Visual Studio:

    • Single-container project: MS_VS_CONTAINERS_TOOLS_LOGGING_ENABLED=1
    • Docker Compose project: MS_VS_DOCKER_TOOLS_LOGGING_ENABLED=1

    For example, in an elevated Command Prompt:

    setx MS_VS_CONTAINERS_TOOLS_LOGGING_ENABLED 1

    Restart Visual Studio, reproduce the error, then read the logs under %TEMP%\Microsoft.VisualStudio.Containers.Tools (or %TEMP%\Microsoft.VisualStudio.DockerCompose.Tools).

Look for errors like:

  • “Container failed to start”
  • “Failed to pull image”
  • “No such file or directory: /remote_debugger/vsdbg”
  • “Network timeout”

Security note: Container Tools diagnostic logs can contain credentials in plain text when the Azure authentication token proxy is enabled. Remove the environment variable when you’re done and scrub secrets before sharing logs.

Use these logs to target the remaining issues (for example, a proxy blocking mcr.microsoft.com, a failed image pull, or a missing debugger dependency).

11. Verify the Container Image Supports the Debugger#

Visual Studio installs vsdbg inside the container at debug time. The install script needs a downloader such as curl or wget, plus unzip and a POSIX shell; the debugger also expects basic process tools. Minimal, hardened, or custom base images often remove them, and the adapter then fails before your app starts.

  1. Check the image that actually runs when you press F5—the final stage for a single-container project, or the debug/build stage for Docker Compose. For example, to check the standard runtime base image:
    docker run --rm --entrypoint sh mcr.microsoft.com/dotnet/aspnet:5.0 -c "command -v curl; command -v unzip; command -v bash; command -v ps"
    A missing path in the output identifies the gap.
  2. Install the prerequisites in your Dockerfile. For Debian-based .NET 5 images:
    RUN apt-get update \
        && apt-get install -y --no-install-recommends curl unzip bash procps \
        && rm -rf /var/lib/apt/lists/*
    For Alpine-based images:
    RUN apk add --no-cache curl unzip bash procps
  3. Make sure the stage Visual Studio debugs still contains the SDK/runtime layout your project expects. If you replaced the generated multi-stage Dockerfile with a runtime-only image, the debugger may have no shell or package manager to work with.
  4. Rebuild without cache and debug again:
    docker build --no-cache -t myapp:debug .

Why this works: The “Failed to Launch Debug Adapter” message is generic; when the underlying error is ERROR: Command 'unzip' not found, ps: not found, or a missing /remote_debugger/vsdbg, the adapter never gets a chance to attach. Adding the missing tools—or restoring the SDK-based debug stage that Visual Studio’s generated multi-stage Dockerfile expects—removes that failure mode.

Troubleshooting FAQs#

Q: I updated Docker and Visual Studio, but the error persists. What now?#

A: Check the container type first (docker info --format "{{.OSType}}") and make sure it matches the project’s Docker OS. For Linux containers:

  • WSL 2 backend (the common default): confirm your distribution is enabled under Docker Desktop > Settings > Resources > WSL integration, and that the project is on a filesystem WSL can access quickly (preferably inside the WSL distribution, not a network drive).
  • Hyper-V backend: enable Settings > Resources > File sharing for the drive that contains the solution. If your Windows password changed, re-toggle the shared drive so Docker can refresh the credentials.

Also clear %USERPROFILE%\vsdbg, delete the .vs folder, and check whether a recent VS update introduced the problem (see step 7).

Q: Does this fix work for Docker Compose projects?#

A: Yes—the same causes apply, with a few differences:

  • Select the docker-compose project as the startup project, and edit the Docker profile in each service’s launchSettings.json.
  • The diagnostic environment variable is MS_VS_DOCKER_TOOLS_LOGGING_ENABLED instead of MS_VS_CONTAINERS_TOOLS_LOGGING_ENABLED.
  • One broken service can block the whole Compose launch. Run docker compose logs and check the service that exits first.
  • If Visual Studio generated docker-compose.vs.debug.yml or docker-compose.vs.release.yml, delete those files (or the .vs folder) so Visual Studio regenerates them.

Q: F5 fails, but I can attach to the running container. What does that mean?#

A: If Debug > Attach to Process > Docker (Linux Container) works and breakpoints bind, your app and image are fine—the launch profile or generated debug files are the problem. Delete the .vs folder and any docker-compose.vs.*.yml files so Visual Studio recreates them, recheck the ports in launchSettings.json, and then try F5 again.

Q: The debug adapter times out. Can I increase the timeout in launchSettings.json?#

A: There is no supported dockerLaunchTimeout property in launchSettings.json; adding one has no effect. A timeout is almost always a symptom of a slow or stuck container start, not a setting that needs a bigger number. Check these in order:

  1. First-run image pull — pre-pull the base images (docker pull mcr.microsoft.com/dotnet/aspnet:5.0 and .../sdk:5.0) so the first F5 isn’t waiting on the network.
  2. Container logs — run docker logs <container> after the failure; a crash on startup (missing connection string, HTTPS certificate, or port binding) looks like a timeout to Visual Studio.
  3. Resource limits — under Docker Desktop > Settings > Resources, give the Docker VM enough memory and CPU; on WSL 2, check .wslconfig for an overly low memory cap.
  4. Antivirus or proxy — security software scanning the project or Docker volumes can stall the build and debugger mount. Add exclusions and retry.
  5. Docker state — reset containers and images (step 5) and clear the stale vsdbg cache.

If you use Docker Compose, launchBrowserTimeout is a real setting, but it only controls how long Visual Studio waits before opening the browser—it does not extend the debugger attach timeout.

Q: .NET 5.0 is unsupported. Should I upgrade?#

A: Yes, for anything beyond short-term legacy maintenance. .NET 5 reached end of support on May 10, 2022, so it no longer receives security patches. As of November 2026:

  • .NET 10 (LTS) is the recommended target, supported until November 14, 2028. Targeting it requires Visual Studio 2026; Visual Studio 2022 cannot target .NET 10.
  • .NET 8 and .NET 9 both reach end of support on November 10, 2026, so they are not good long-term choices either.

Use the .NET Upgrade Assistant to migrate, and move your container images to the matching mcr.microsoft.com/dotnet/aspnet and sdk tags. If you can’t move to Visual Studio 2026 immediately, keep the .NET 5 project isolated and plan the jump to .NET 10 rather than spending time on .NET 8/9, which are days away from end of support.

Conclusion#

The "Failed to Launch Debug Adapter" error in Visual Studio 2022 for .NET 5.0 Docker projects is typically caused by misconfigurations, missing dependencies, or environmental conflicts. By following the steps above—updating tools, verifying SDKs, cleaning builds, and checking ports—you can resolve the issue and get back to debugging.

If you’re still stuck, collect the Container Tools and docker logs output described in step 10 to pinpoint the failing stage, then work backward from there. And because .NET 5 is out of support, plan a migration to .NET 10 (LTS)—or another currently supported release—for security patches and a smoother container debugging experience.

References#