Skip to content

add faq note for localhost.localstack.cloud not resolving on Windows #1749

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

add faq note for localhost.localstack.cloud not resolving on Windows #1749

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions content/en/getting-started/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,32 @@ volumes:

For more details visit [Docker WSL documentation](https://docs.docker.com/desktop/wsl), [Docker WSL best practices](https://docs.docker.com/desktop/wsl/best-practices) and [Docker Volumes documentation](https://docs.docker.com/storage/volumes/).

### Why is `localhost.localstack.cloud` not resolving on Windows with WSL, and how do I fix it?

We’ve seen multiple reports where requests to `localhost.localstack.cloud` fail specifically when running on **Windows with WSL (Windows Subsystem for Linux)**.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think I'd call out that we had multiple reports of this, our customers don't need to know that.
Here's my suggested update to the whole file.

Why can't I connect to localhost.localstack.cloud when using WSL on Windows?

Symptom:

You might encounter issues where localhost.localstack.cloud (or other *.localhost.localstack.cloud subdomains) do not resolve correctly when you are using LocalStack on Windows with the Windows Subsystem for Linux (WSL). This can manifest as tools like curl inside WSL, or even your browser on Windows, failing to connect to services exposed by LocalStack via these domains.

Cause:

This is typically a DNS resolution problem. Your WSL distribution and/or your Windows host system may not be configured to resolve localhost.localstack.cloud (and its subdomains) to the loopback IP address (127.0.0.1).

Solution:

To ensure that localhost.localstack.cloud resolves correctly in both your WSL environment and on your Windows host, you'll need to manually update the hosts file in both locations.

  1. Update the hosts file in your WSL distribution:

    • Open your WSL terminal (e.g., Ubuntu, Debian).
    • Edit the /etc/hosts file using a text editor with root privileges. For example, with nano: 
      sudo nano /etc/hosts
    • Add the following line to the file: 
      127.0.0.1 localhost.localstack.cloud
    • If you use other subdomains like s3.localhost.localstack.cloud, you can add them on the same line or as separate entries pointing to 127.0.0.1: 
      127.0.0.1 localhost.localstack.cloud s3.localhost.localstack.cloud
    • Save the file and exit the editor (in nano, press Ctrl+X, then Y, then Enter).

  2. Update the hosts file on your Windows system:

    • You will need Administrator privileges to edit the Windows hosts file.
    • Open Notepad (or your preferred text editor) as an Administrator. (Search for Notepad, right-click, "Run as administrator").
    • In the editor, open the following file: C:\Windows\System32\drivers\etc\hosts
    • Add the same line(s) you added to your WSL hosts file: 
      127.0.0.1 localhost.localstack.cloud
# Add other subdomains if needed, e.g.:
# 127.0.0.1 s3.localhost.localstack.cloud
# 127.0.0.1 my-bucket.s3.localhost.localstack.cloud
    • Save the file.

  3. Flush the DNS cache on Windows:

    • Open Command Prompt or PowerShell as an Administrator.
    • Run the following command: 
      ipconfig /flushdns

After completing these steps, your system should correctly resolve localhost.localstack.cloud (and any other specified subdomains) to 127.0.0.1, allowing your applications in both WSL and Windows to connect to LocalStack services.

In this scenario, tools like `curl` and LocalStack Web Application cannot connect to LocalStack container using the domain `localhost.localstack.cloud`.

This is a DNS resolution issue — the system doesn’t know that `localhost.localstack.cloud` should resolve to `127.0.0.1`.
Follow these steps to fix the issue:

1. **Update WSL DNS mapping:** Edit `/etc/hosts` in your WSL environment to include this line:

```text
127.0.0.1 localhost localhost.localstack.cloud
```

This allows tools like `curl` in WSL to resolve the domain properly.

2. **Update Windows DNS mapping:** Edit `C:\Windows\System32\drivers\etc\hosts` (as Administrator) and add the same line:

```text
127.0.0.1 localhost localhost.localstack.cloud
```

After updating, reboot your system or run `ipconfig /flushdns` to clear the DNS cache.

Once both changes are in place, the domain should resolve correctly for both WSL and Windows apps.

## LocalStack Platform FAQs

### Where can I check the status of LocalStack's services?
Expand Down