Fix mirrored networking loopback endpoint creation failure by benm-dev · Pull Request #14081 · microsoft/WSL

benm-dev · 2026-01-18T11:08:40Z

Summary of the Pull Request

Fix loopback endpoint creation failure in mirrored networking mode after KB5074109.

PR Checklist

Closes: WSL mirror network mode is broken in the latest stable windows update #14080
Communication: Issue documented and investigated
Tests: Manual validation performed (see below)
Localization: No user-facing strings
Dev docs: N/A
Documentation updated: N/A

Detailed Description

After KB5074109, HNS loopback networks reject firewall policies when creating endpoints, returning error 0x803B001B. This fix detects loopback networks via IsLoopback property and uses simplified endpoint settings without policies.

Validation Steps Performed

Direct HCN API testing confirmed:
- Endpoint WITH firewall policy → 0x803B001B (FAIL)
- Endpoint with HostComputeNetwork only → 0x00000000 (SUCCESS)
WSL localhost TCP connectivity verified working with correct endpoint settings
Tested on Windows Build 26220.7535

benm-dev · 2026-01-18T11:09:43Z

@microsoft-github-policy-service agree

Copilot

Pull request overview

This PR fixes a critical bug in mirrored networking mode where loopback endpoint creation fails after Windows update KB5074109. The fix detects loopback networks and uses simplified endpoint settings without firewall policies to avoid HCN error 0x803B001B.

Changes:

Added loopback network detection logic to skip firewall policy application
Created separate endpoint configuration path for loopback networks using HostComputeNetwork
Extended HNSNetwork schema to include IsLoopback property for network type detection

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/windows/service/exe/MirroredNetworking.cpp	Added conditional logic to detect loopback networks and configure endpoints without firewall policies, using HostComputeNetwork instead of VirtualNetwork
src/shared/inc/hns_schema.h	Added IsLoopback boolean field to HNSNetwork struct with JSON serialization support

offsechq · 2026-01-18T13:51:24Z

lgtm

ikifar2012 · 2026-01-18T20:34:13Z

Is this the same as issue #13454

offsechq · 2026-01-18T22:27:17Z

Doesn't look like it, that is more generic and solvable by resetting the adapter as the reply here

benhillis · 2026-01-20T16:19:08Z

@keith-horton - does this look reasonable to you? Do you have any context on the Windows change that recently broke this?

keith-horton · 2026-01-24T01:31:07Z

@keith-horton - does this look reasonable to you? Do you have any context on the Windows change that recently broke this?

The fix referred to in that KB article was not in WSL - it was in other parts of the TCPIP / vswitch stack - where we addressed a perf issue, but the NBL (kernel structure representing one or more packets) could have fields that some VPN vendors did not expect (though was perfectly legal) -- which was exercised in the WSL path. So we had to revert that and fix it in a way that did not break some VPNs.

So I don't know what would have changed that would have affected the above.

The author of this PR is correct: Hyper-V Firewall rules do not affect the loopback path.

keith-horton

Thank you for doing this investigation and testing.

WSL supports older versions of Windows that does not support Hyper-V Firewall. This looks correct to me - minus the change I noted below.

ptrivedi · 2026-01-28T15:54:26Z

+            // Loopback networks require HostComputeNetwork (not VirtualNetwork) and don't support policies
+            hns::HostComputeEndpoint hnsEndpoint{};
+            hnsEndpoint.HostComputeNetwork = NetworkId;
+            hnsEndpoint.SchemaVersion.Major = 2;


nit: assuming these version numbers are hardcoded elsewhere too. Would be good to declare named constant that can be repeatedly used

yeah I worry a little bit about this schema version, do we know everywhere that supports mirrored networking supports 2.16?

benm-dev · 2026-01-28T23:42:24Z

Hi @keith-horton , I updated this in commit c61ba69 - the condition now reads:

else if (m_config.FirewallConfig.Enabled() && isLoopbackNetwork)

The diff you're viewing is marked "Outdated" which shows the old code. Let me know if there's anything else needed!

keith-horton

Great. Thanks for doing this!

offsechq · 2026-02-11T17:34:19Z

Can't wait till it find the way to production soon! thanks a lot

kmj251 · 2026-02-19T18:07:57Z

Is there an update on when this PR will be merged and a new release created?

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/windows/service/exe/MirroredNetworking.cpp:501

Loopback networks are only handled specially when Hyper-V Firewall is enabled. If properties.IsLoopback is true and m_config.FirewallConfig.Enabled() is false, the code still builds endpoint settings with HNSEndpoint::VirtualNetwork = NetworkId, but the comment/PR description states loopback endpoints require HostComputeNetwork and fail when created with the other schema. Consider moving the loopback handling outside the firewall-enabled branch so loopback endpoints always use HostComputeEndpoint (without policies) regardless of firewall configuration.

        else if (m_config.FirewallConfig.Enabled() && isLoopbackNetwork)
        {
            // Loopback networks require HostComputeNetwork (not VirtualNetwork) and don't support policies
            hns::HostComputeEndpoint hnsEndpoint{};
            hnsEndpoint.HostComputeNetwork = NetworkId;
            hnsEndpoint.SchemaVersion.Major = 2;
            hnsEndpoint.SchemaVersion.Minor = 16;
            endpointSettings = ToJsonW(hnsEndpoint);
        }
        else
        {
            // If Hyper-V Firewall is not supported for this scenario, only configure the basic HNS endpoint object
            wsl::shared::hns::HNSEndpoint settings{};
            settings.VirtualNetwork = NetworkId;
            endpointSettings = ToJsonW(settings);
        }

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

+        // Loopback networks don't support firewall policies - creating an endpoint with firewall
+        // policies on a loopback network will fail with HCN error 0x803B001B ("Invalid JSON document
+        // string"). This behavior changed in KB5074109. Additionally, loopback networks require
+        // HostComputeNetwork instead of VirtualNetwork in the endpoint settings.
+        // See: https://github.com/microsoft/WSL/issues/14080
+        const bool isLoopbackNetwork = properties.IsLoopback;


Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

## Problem After installing KB5074109 (January 2026), WSL mirrored networking fails to create the loopback endpoint, causing localhost (127.0.0.1) TCP/UDP connections to fail. Users see the loopback0 interface in state DOWN with NO-CARRIER. ## Root Cause Analysis HNS loopback networks no longer accept firewall policies when creating endpoints. Direct HCN API testing confirms: - Test 1: Endpoint WITH firewall policy -> 0x803B001B (FAIL) Error: 'Invalid JSON document string. {{Policies.VmCreatorId,UnknownField}}' - Test 2: Endpoint with VirtualNetwork field -> 0x803B001B (FAIL) Error: 'Invalid JSON document string. {{VirtualNetwork,UnknownField}}' - Test 3: Endpoint with HostComputeNetwork only -> 0x00000000 (SUCCESS) The current code in MirroredNetworking::AddNetworkEndpoint() creates all endpoints with firewall policies when m_config.FirewallConfig.Enabled() is true (the default), causing loopback endpoint creation to fail silently. ## Solution - Add IsLoopback field to HNSNetwork struct to detect loopback networks - Skip firewall policies when creating endpoints on loopback networks - Use HostComputeNetwork instead of VirtualNetwork for loopback endpoints ## Testing Verified on Windows Build 26220.7535: 1. HCN API tests confirm endpoint creation succeeds without firewall policies 2. WSL localhost TCP connectivity works when loopback0 is properly configured Fixes microsoft#14080 Related: microsoft#14063

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

benhillis · 2026-04-04T00:04:19Z

/azp run

azure-pipelines · 2026-04-04T00:04:29Z

Azure Pipelines successfully started running 1 pipeline(s).

benhillis · 2026-04-04T00:04:53Z

@benm-dev - sorry this one slipped through the cracks, taking a look now.

…licy

azure-pipelines · 2026-04-15T20:12:18Z

Commenter does not have sufficient privileges for PR 14081 in repo microsoft/WSL

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Copilot · 2026-04-15T20:26:57Z

+    bool IsLoopback{};

-    NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(HNSNetwork, ID, Name, SourceMac, DNSSuffix, DNSServerList, DNSDomain, Subnets, Flags, InterfaceConstraint);
+    NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(HNSNetwork, ID, Name, SourceMac, DNSSuffix, DNSServerList, DNSDomain, Subnets, Flags, InterfaceConstraint, IsLoopback);


Adding IsLoopback to NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT changes both deserialization and serialization for HNSNetwork. If HNSNetwork is ever serialized for outbound HNS/HCN requests, this will now emit an IsLoopback field (default false), which could be rejected as an unexpected property. Consider either (1) making IsLoopback response-only via a custom to_json/from_json that omits it on serialization, or (2) splitting request vs response DTOs so response-only properties don’t get sent back to the platform.

Suggested change

NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(HNSNetwork, ID, Name, SourceMac, DNSSuffix, DNSServerList, DNSDomain, Subnets, Flags, InterfaceConstraint, IsLoopback);

friend void to_json(nlohmann::json& Json, const HNSNetwork& Network)

{

Json = nlohmann::json{

{"ID", Network.ID},

{"Name", Network.Name},

{"SourceMac", Network.SourceMac},

{"DNSSuffix", Network.DNSSuffix},

{"DNSServerList", Network.DNSServerList},

{"DNSDomain", Network.DNSDomain},

{"Subnets", Network.Subnets},

{"Flags", Network.Flags},

{"InterfaceConstraint", Network.InterfaceConstraint},

};

}

friend void from_json(const nlohmann::json& Json, HNSNetwork& Network)

{

Network = HNSNetwork{};

if (const auto Entry = Json.find("ID"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.ID);

}

if (const auto Entry = Json.find("Name"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.Name);

}

if (const auto Entry = Json.find("SourceMac"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.SourceMac);

}

if (const auto Entry = Json.find("DNSSuffix"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.DNSSuffix);

}

if (const auto Entry = Json.find("DNSServerList"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.DNSServerList);

}

if (const auto Entry = Json.find("DNSDomain"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.DNSDomain);

}

if (const auto Entry = Json.find("Subnets"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.Subnets);

}

if (const auto Entry = Json.find("Flags"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.Flags);

}

if (const auto Entry = Json.find("InterfaceConstraint"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.InterfaceConstraint);

}

if (const auto Entry = Json.find("IsLoopback"); Entry != Json.end() && !Entry->is_null())

{

Entry->get_to(Network.IsLoopback);

}

}

…licy

benhillis · 2026-04-20T22:52:22Z

/azp run

azure-pipelines · 2026-04-20T22:52:31Z

Azure Pipelines successfully started running 1 pipeline(s).

benhillis · 2026-04-22T20:48:49Z

@benm-dev — latest CI is failing on formatting checks. Please rebase on master and run .\FormatSource.ps1.

benm-dev requested a review from a team as a code owner January 18, 2026 11:08

benm-dev requested review from Brian-Perkins, OneBlue, benhillis, Copilot and craigloewen-msft January 18, 2026 11:08

Copilot started reviewing on behalf of benm-dev January 18, 2026 11:09 View session

Copilot AI reviewed Jan 18, 2026

View reviewed changes

benhillis added the network label Jan 20, 2026

benhillis requested a review from keith-horton January 20, 2026 16:18

benhillis assigned keith-horton Jan 20, 2026

keith-horton requested changes Jan 24, 2026

View reviewed changes

Comment thread src/windows/service/exe/MirroredNetworking.cpp Outdated

benm-dev requested a review from keith-horton January 27, 2026 05:13

ptrivedi reviewed Jan 28, 2026

View reviewed changes

keith-horton requested changes Jan 28, 2026

View reviewed changes

Comment thread src/windows/service/exe/MirroredNetworking.cpp Outdated

benm-dev requested a review from keith-horton January 28, 2026 23:46

keith-horton previously approved these changes Jan 29, 2026

View reviewed changes

benhillis reviewed Feb 2, 2026

View reviewed changes

Comment thread src/windows/service/exe/MirroredNetworking.cpp

offsechq mentioned this pull request Feb 5, 2026

WSL mirror network mode is broken in the latest stable windows update #14080

Open

2 tasks

benhillis force-pushed the fix/mirrored-loopback-endpoint-firewall-policy branch from 65c96d9 to 94ac6f9 Compare February 11, 2026 16:22

Copilot AI review requested due to automatic review settings March 12, 2026 19:04

benm-dev requested a review from benhillis March 18, 2026 23:05

Copilot AI reviewed Mar 18, 2026

View reviewed changes

Comment thread src/windows/service/exe/MirroredNetworking.cpp Outdated

benm-dev dismissed keith-horton’s stale review via 9d6818f March 18, 2026 23:10

Copilot AI review requested due to automatic review settings March 18, 2026 23:10

Copilot AI reviewed Mar 18, 2026

View reviewed changes

benhillis force-pushed the fix/mirrored-loopback-endpoint-firewall-policy branch from 9d6818f to e57f5cf Compare March 19, 2026 19:49

benm-dev requested a review from Copilot March 19, 2026 21:22

Copilot started reviewing on behalf of benm-dev March 19, 2026 21:24 View session

Copilot AI reviewed Mar 19, 2026

View reviewed changes

Comment thread src/windows/service/exe/MirroredNetworking.cpp

Comment thread src/windows/service/exe/MirroredNetworking.cpp Outdated

benm-dev and others added 3 commits March 27, 2026 12:35

update loopback network endpoint firewall policy check

95534f5

Potential fix for pull request finding

1004388

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 27, 2026 19:35

benhillis force-pushed the fix/mirrored-loopback-endpoint-firewall-policy branch from fa21b2b to 1004388 Compare March 27, 2026 19:35

Copilot started reviewing on behalf of benhillis March 27, 2026 19:39 View session

Copilot AI reviewed Mar 27, 2026

View reviewed changes

Comment thread src/windows/service/exe/MirroredNetworking.cpp

Merge branch 'master' into fix/mirrored-loopback-endpoint-firewall-po…

e88b6c6

…licy

Update src/windows/service/exe/MirroredNetworking.cpp

9014f79

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 15, 2026 20:19

Copilot AI reviewed Apr 15, 2026

View reviewed changes

Copilot started reviewing on behalf of benm-dev April 15, 2026 20:43 View session

keith-horton approved these changes Apr 15, 2026

View reviewed changes

Merge branch 'master' into fix/mirrored-loopback-endpoint-firewall-po…

4e0fdab

…licy

-    NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(HNSNetwork, ID, Name, SourceMac, DNSSuffix, DNSServerList, DNSDomain, Subnets, Flags, InterfaceConstraint, IsLoopback);
+    friend void to_json(nlohmann::json& Json, const HNSNetwork& Network)
+    {
+        Json = nlohmann::json{
+            {"ID", Network.ID},
+            {"Name", Network.Name},
+            {"SourceMac", Network.SourceMac},
+            {"DNSSuffix", Network.DNSSuffix},
+            {"DNSServerList", Network.DNSServerList},
+            {"DNSDomain", Network.DNSDomain},
+            {"Subnets", Network.Subnets},
+            {"Flags", Network.Flags},
+            {"InterfaceConstraint", Network.InterfaceConstraint},
+        };
+    }
+    friend void from_json(const nlohmann::json& Json, HNSNetwork& Network)
+    {
+        Network = HNSNetwork{};
+        if (const auto Entry = Json.find("ID"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.ID);
+        }
+        if (const auto Entry = Json.find("Name"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.Name);
+        }
+        if (const auto Entry = Json.find("SourceMac"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.SourceMac);
+        }
+        if (const auto Entry = Json.find("DNSSuffix"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.DNSSuffix);
+        }
+        if (const auto Entry = Json.find("DNSServerList"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.DNSServerList);
+        }
+        if (const auto Entry = Json.find("DNSDomain"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.DNSDomain);
+        }
+        if (const auto Entry = Json.find("Subnets"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.Subnets);
+        }
+        if (const auto Entry = Json.find("Flags"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.Flags);
+        }
+        if (const auto Entry = Json.find("InterfaceConstraint"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.InterfaceConstraint);
+        }
+        if (const auto Entry = Json.find("IsLoopback"); Entry != Json.end() && !Entry->is_null())
+        {
+            Entry->get_to(Network.IsLoopback);
+        }
+    }

Conversation

benm-dev commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of the Pull Request

PR Checklist

Detailed Description

Validation Steps Performed

Uh oh!

benm-dev commented Jan 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

offsechq commented Jan 18, 2026

Uh oh!

ikifar2012 commented Jan 18, 2026

Uh oh!

offsechq commented Jan 18, 2026

Uh oh!

benhillis commented Jan 20, 2026

Uh oh!

keith-horton commented Jan 24, 2026

Uh oh!

keith-horton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ptrivedi Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

benhillis Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

benm-dev commented Jan 28, 2026

Uh oh!

keith-horton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

offsechq commented Feb 11, 2026

Uh oh!

kmj251 commented Feb 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

benhillis commented Apr 4, 2026

Uh oh!

azure-pipelines Bot commented Apr 4, 2026

Uh oh!

benhillis commented Apr 4, 2026

Uh oh!

azure-pipelines Bot commented Apr 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Apr 15, 2026

benm-dev commented Jan 18, 2026 •

edited

Loading