Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
If WSL2 reports Temporary failure in name resolution after Docker Desktop starts, first find out whether DNS fails in the WSL shell, only inside containers, or only when Docker accesses a registry. Those are different failure points and need different fixes. Start with the checks below, then work from low-risk restarts and supported Docker settings toward VPN, firewall, or resolver changes.
In WSL2’s default NAT mode, DNS requests pass through a Windows-host NAT device and the Windows SharedAccess service. Docker containers add a separate network namespace, so a resolver that works in WSL may still fail inside a container. Microsoft’s WSL troubleshooting documentation and Docker’s daemon troubleshooting guidance describe these separate paths.
What does “Temporary failure in name resolution” mean?
It means the system making the request could not resolve the hostname to an IP address at that moment. It does not, by itself, prove that the internet connection is down or that Docker is the cause. The key is to identify which resolver path is failing.
In default WSL2 NAT mode, a Linux distribution sends DNS queries to a NAT device on the Windows host. The query is forwarded through Windows SharedAccess, and the response returns to WSL. Microsoft says this path depends on a firewall rule created by the Host Network Service (HNS) that permits the DNS traffic. Windows firewall policy can therefore block WSL lookups even when the Linux distribution’s configuration looks plausible.
Popular on Amazon
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
A container has another resolver boundary: its own network namespace. A DNS address such as 127.0.0.1 refers to the container itself, not automatically to WSL or Windows. A working lookup in Ubuntu and a failed lookup in a container can therefore coexist.
How can I tell whether WSL, Docker, or the registry is failing?
Run the WSL checks first, then test a disposable container and a real image pull. Compare the results before changing DNS settings.
1. Test name resolution in the WSL distribution
cat /etc/resolv.conf
getent hosts google.com
getent hosts registry-1.docker.iocat shows the resolver configuration WSL is presenting to Linux. The getent commands test whether the distribution can resolve a public hostname and Docker’s registry hostname through its configured name service. If your organization uses internal hostnames, also test an approved internal name while connected to the relevant network or VPN.
2. Test resolution from a container
docker run --rm busybox nslookup google.comThis checks the container’s resolver path rather than just WSL’s. Docker documents docker pull hello-world as a practical DNS and registry-access check, but a pull tests more than DNS; use it after the resolver checks.
docker pull hello-worldUse this interpretation:
- WSL lookup fails and container lookup fails: investigate WSL DNS generation, Windows networking or firewall policy, and VPN behavior first.
- WSL lookup works but container lookup fails: focus on Docker Desktop’s networking and the container-side resolver. Do not start by overwriting WSL’s resolver file.
- Both lookups work but the image pull fails: test the registry path and investigate proxy settings, registry access, TLS, authentication, or Docker Desktop’s backend state. A failed pull alone does not establish a DNS failure.
What should I try before changing DNS configuration?
Stop WSL completely, restart Docker Desktop, and then reopen the distribution. This is a low-risk way to clear stale subsystem or networking state before making persistent changes.
In PowerShell, run:
wsl --shutdownWait for WSL to stop, start or confirm Docker Desktop is running, and then reopen your distribution. You can check whether any distributions are still running with:
wsl --list --runningMicrosoft documents wsl --shutdown as the fast way to stop all WSL2 distributions; its documentation describes an approximately eight-second stop rule. Configuration changes to WSL require the subsystem to stop and restart to take effect. If the error returns immediately, continue with the layer-specific checks rather than repeatedly rebooting without changing or identifying anything.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsHow do I check Docker Desktop’s WSL integration?
Confirm that the affected distribution is running as WSL2 and that Docker Desktop has integration enabled for it. These checks matter especially when Docker commands behave differently between distributions or Docker Desktop has recently been reconfigured.
Also popular on Amazon
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
- In PowerShell, run
wsl.exe -l -v. Find the affected distribution and check that its version is2. If it shows version1, it is not using the WSL2 environment described here. - In Docker Desktop, open Settings > Resources > WSL Integration and make sure integration is enabled for the distribution you are using. Docker says integration is enabled for the default distribution by default, but this can be changed.
- Confirm Docker Desktop is in Linux-container mode if you are trying to run Linux containers.
- Check whether you installed Docker Engine or the Docker CLI directly inside the distribution. Docker warns that installing those components inside WSL can conflict with Docker Desktop’s WSL2 backend. If you intentionally maintain a separate in-distribution Docker setup, distinguish its daemon and context from Docker Desktop before changing either one.
Docker’s WSL2 backend documentation has listed WSL 2.1.5 as a minimum and recommends using the latest WSL version to avoid Docker Desktop problems. Requirements can change, so check the current Docker Desktop and WSL release documentation for the version you have rather than treating that historical minimum as a guarantee for every later release. Use wsl --version to see the installed WSL version where that command is available.
How should I inspect /etc/resolv.conf?
Inspect the file for a usable nameserver entry, but do not delete or permanently replace WSL’s generated resolver configuration as a first step. Microsoft documents generateResolvConf=true as the default, meaning WSL normally generates this file.
Run:
cat /etc/resolv.confIf the file is missing, empty, stale, or points to a resolver that cannot be reached, that is useful evidence of a WSL DNS or Windows networking problem. It is not enough to conclude that a public DNS address will fix the underlying path. WSL may need to reach a Windows-host NAT resolver, a VPN-provided DNS service, or an organization’s internal resolver.
Avoid hard-coding 8.8.8.8 or another public nameserver as a universal remedy. Public DNS may resolve public sites but fail to resolve internal company names and services. It can also bypass DNS policies required by a VPN. If a managed device or VPN supplies DNS, preserve that behavior unless the network administrator directs otherwise.
What should I do if DNS fails only when a VPN is connected?
For a typical Windows VPN, Microsoft recommends WSL DNS tunneling because it lets WSL queries follow Windows DNS policies, including NRPT rules. However, Microsoft documents a separate Global Secure Access interaction with a different recommended workaround, so do not apply one VPN fix to every security client.
For a normal Windows VPN, check DNS tunneling
Microsoft documents the following global WSL setting in %UserProfile%.wslconfig:
[wsl2]
dnsTunneling=trueIf you change the setting, save the file and run wsl --shutdown in PowerShell before reopening WSL. DNS tunneling can apply Windows DNS suffixes to Linux and removes the three-server limitation of Linux’s /etc/resolv.conf. Whether it is suitable depends on the VPN and the organization’s configuration.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchFor Global Secure Access, check Microsoft’s exception
Microsoft documents a Global Secure Access case in which temporary DNS addresses can be replaced later, breaking WSL traffic. For that specific interaction, Microsoft’s stated workaround is to disable DNS tunneling or use networkingMode=nat. Do not treat this exception as a general recommendation to turn tunneling off for all VPNs.
Also popular on Amazon
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Microsoft also documents route problems with Cisco AnyConnect in WSL NAT mode and points to administrator guidance. If a corporate VPN is involved, consult the organization’s current support guidance before altering routing or DNS policy.
Use a temporary VPN resolver override only when necessary
If a VPN-specific manual override is unavoidable, first identify the DNS servers actually supplied by the VPN. Microsoft documents this reversible starting point:
ipconfig.exe /all
sudo cp /etc/resolv.conf /etc/resolv.conf.bakUse the VPN’s real DNS address; do not substitute an invented or generic value. After disconnecting the VPN, restore WSL’s generated resolver configuration as Microsoft documents rather than leaving a stale VPN nameserver in place. A manual override can appear to solve one connection state while breaking lookups after the VPN disconnects or its DNS changes.
Could Windows firewall policy block WSL DNS?
Yes. Microsoft says WSL’s NAT-mode DNS path relies on an HNS-created firewall rule for DNS traffic, and enterprise policy can prevent that rule from taking effect. On a managed computer, the durable repair may require an administrator rather than a Linux-side edit.
Microsoft identifies policy conditions that can interfere with the rule, including:
AllowLocalFirewallRules: False, which causes locally created HNS rules to be ignored.AllowInboundRules: False, which prevents the HNS rule from applying.- A Windows Security setting that blocks all incoming connections, including allowed apps.
- Group Policy or mobile-device-management policy that blocks firewall exceptions.
Do not disable endpoint protection, turn off the firewall, or weaken an organization’s inbound policy to test a workaround. If the WSL shell cannot resolve names and the computer is managed, give the administrator the exact failing commands and ask them to check whether the approved WSL DNS path or DNS tunneling is permitted.
What if WSL can resolve names but Docker containers cannot?
That result points toward Docker’s resolver path or container network configuration, not necessarily WSL’s /etc/resolv.conf. Check Docker Desktop networking and confirm that the container is not being given a loopback resolver that only exists on its own network namespace.
Free tools Windows power users keep installed
One-click scans. No signup required.
Docker notes that a container uses its own network namespace. As a result, 127.0.0.1 and 127.0.1.1 inside a container point back to that container; they do not automatically point to a DNS service on the host. If a container’s resolver configuration contains a loopback address, it may be unusable there even if the same address works on a Linux host.
Also popular on Amazon
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Widely Compatible: Transform any USB-C port into a USB-A port and USB-A port into a USB-C port, and connect up a wide range of USB-C(including MacBook, iPad Pro/Air/Mini, iPhone models with USB C ports, Samsung Galaxy series, and Google Pixel series. ) and USB A devices(including external hard drives, phones, mice, printers, and more)
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
For a standalone Linux Docker Engine, Docker documents configuring DNS servers in /etc/docker/daemon.json, then restarting the daemon and verifying with docker pull hello-world. Its example is:
{
"dns": ["8.8.8.8", "8.8.4.4"]
}This example is for standalone Linux Docker Engine guidance; do not assume that editing this file inside a WSL distribution configures Docker Desktop’s Windows-managed daemon in the same way. For Docker Desktop on Windows, start with its supported settings and WSL integration. If internal company names must resolve, use organization-approved DNS servers rather than copying the public addresses in Docker’s example.
Which Docker Desktop network settings are worth checking?
Docker Desktop’s Network settings control default networking mode and DNS resolution behavior. Check them after determining that the failure is in Docker or container networking; switching modes indiscriminately can introduce new compatibility problems without fixing the original fault.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Docker documents dual IPv4/IPv6 as the default networking mode and Auto (recommended) as a DNS behavior option that filters unsupported record types. IPv4-only or IPv6-only modes may be relevant when the host environment cannot use one address family, but neither is a universal WSL DNS repair. Docker also says these settings can be overridden per network or in Compose configuration, so a single failing project may have a local setting that differs from the desktop default.
Use the current Docker Desktop Settings labels shown in your installed version; UI names can change. Change one relevant setting at a time, then rerun the WSL and container checks so you know whether the change affected the failing layer.
Should I switch to mirrored networking?
Not as a reflex. Microsoft describes mirrored networking as experimental and documents a known Docker Desktop issue when containers publish ports in the default networking namespace. If mirrored mode is already enabled, check that compatibility caveat before changing unrelated settings. A network-mode change has a wider scope than a resolver check and can affect port publishing and other connectivity.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.How do I verify the repair and undo temporary changes?
A repair is convincing only when the check that previously failed now succeeds, and any required internal hostname still resolves. Retest WSL and Docker separately:
getent hosts google.com
docker run --rm busybox nslookup google.com
docker pull hello-worldIf your work depends on internal domains, test an organization-approved internal hostname as well. Public lookup success does not establish that VPN suffixes or private zones are working.
Also popular on Amazon
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Undo temporary changes that no longer apply. After disconnecting from a VPN, restore the generated /etc/resolv.conf if you used a manual VPN resolver override. If you changed .wslconfig temporarily, revert the setting and run wsl --shutdown again so the subsystem restarts with the restored configuration. Keep a note of which change fixed which failing check; that makes later VPN or network transitions easier to diagnose.
How should I choose between the possible fixes?
Choose the smallest change that targets the failing layer and preserves the DNS names your environment needs. The best repair is not necessarily the one that makes a public hostname resolve; it should also suit the VPN, internal domains, Docker setup, and security policy in use.
- Scope: Is the problem in the WSL shell, a container, Docker Desktop’s backend, VPN routing, or Windows firewall policy?
- Persistence: Is a restart sufficient, or is a persistent
.wslconfigor Docker setting actually needed? - DNS fidelity: Will the change preserve corporate suffixes and internal names, or send queries to a public resolver that cannot answer them?
- Administrative control: Can you change the setting yourself, or does Group Policy, MDM, or VPN policy require an administrator?
- Compatibility: Does the proposed change affect NAT, DNS tunneling, mirrored networking, IPv4/IPv6 handling, or a security client?
- Rollback: Can you restore the generated resolver or prior configuration when VPN or network state changes?
A Microsoft WSL issue opened on April 10, 2024 recorded the same symptom after Docker Desktop started: ping google.com returned Temporary failure in name resolution. That report described Windows 10 build 19045.4170, WSL 2.1.5.0, Ubuntu 22.04.4, and Docker Desktop 4.29.0. It confirms that this symptom has occurred, but it does not establish that a workaround for those historical versions is appropriate for a current setup.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Frequently Asked Questions
Why does Docker DNS work until I connect to a VPN?
A VPN can change DNS servers, suffixes, routes, or Windows name-resolution policy after WSL has started. If the issue occurs only on one VPN, record whether WSL DNS tunneling is enabled and ask the VPN or IT administrator to check the supported WSL configuration for that specific client.
Can I use a Windows hosts-file entry to fix a WSL or container DNS error?
A hosts-file entry is a local name-to-address mapping, not a repair for an unreachable DNS resolver. It may also fail to help a container if that container does not receive the relevant mapping, so verify the hostname from the exact environment that needs it.
Why can an IP address work when a hostname does not?
Connecting by IP can bypass DNS lookup, which is why it can distinguish a name-resolution symptom from some connectivity problems. It does not confirm that the destination is reachable for every protocol, nor does it fix DNS for other hostnames or Docker registry access.
Does ping prove that Docker DNS is broken?
No. A failed hostname lookup in ping shows a name-resolution problem in the environment running that command, but it does not test the separate resolver path inside a container. Use a container-side lookup such as docker run --rm busybox nslookup google.com to check that layer.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
