Help debugging why nitric run doesn't work for ts-sarter project in WSL2

[miguelh72]

I am on a windows 11 using WSL2 with Debian. I've followed all instructions to setup Docker and DockerX and have used it many times in the current setup with other projects. Here is more system info:

$ cat /etc/debian_version
12.8
$ docker --version
Docker version 27.5.1, build 9f9e405
$ docker buildx version
github.com/docker/buildx v0.20.1-desktop.2 aaf7c2bc7f9ec3afee1cec77d671845a4b57a0c8
>wsl --version
WSL version: 2.3.26.0
Kernel version: 5.15.167.4-1
WSLg version: 1.0.65
MSRDC version: 1.2.5620
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.26100.3194

Steps to reproduce the problem with error message:

$ nitric new hello-world ts-starter

  proj    Project Created!

          Navigate to your project with cd ./hello-world   
          Install dependencies and you're ready to rock! 🪨
                                                           
          Need help? Come and chat https://nitric.io/chat  
                                                           


$ cd hello-world/
hello-world$ npm i

added 91 packages, and audited 92 packages in 7s

8 packages are looking for funding
  run `npm fund` for details

2 moderate severity vulnerabilities

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.
hello-world$ nitric run
Local cloud started successfully
 build   Building Services.                                                                               
                                                                                                          
         hello-world_services-api complete                                                                
                                                                                                          
┌───────────────────────────────────────────────────────────────────────────────────────────────────┐
│1 services registered with local │ internal/process/task_queues:77:11) {                           │
│nitric server                    │   code: 14,                                                     │
│                                 │   details: 'No connection established. Last err                 │
│                                 │ or: connect ECONNREFUSED 172.17.0.1:29501 (2025-02-23T18:43:05.1│
│                                 │ 64Z)',                                                          │
│                                 │   metadata: Metadata { internalRepr: Map(0) {},                 │
│                                 │  options: {} }                                                  │
│                                 │ }                                                               │
│                                 │                                                                 │
│                                 │ Node.js v22.4.1                                                 │
│                                 │ services/api.ts:                                                │
│                                 │                                                                 │
└───────────────────────────────────────────────────────────────────────────────────────────────────┘
 error  service hello-world_services-api exited with non 0 status
     at ServiceClientImpl.serve (/usr/app/lib/index.js:6329:19)
    at Method.<anonymous> (/usr/app/lib/index.js:28648:34)
    at Generator.next (<anonymous>)
    at /usr/app/lib/index.js:14837:61
    at new Promise (<anonymous>)
    at __async (/usr/app/lib/index.js:14821:10)
    at /usr/app/lib/index.js:28638:39
    at /usr/app/lib/index.js:27909:24
    at Generator.next (<anonymous>)
Emitted 'error' event on ClientDuplexStreamImpl instance at:
    at Object.onReceiveStatus (/usr/app/lib/index.js:2485:28)
    at Object.onReceiveStatus (/usr/app/lib/index.js:1954:181)
    at /usr/app/lib/index.js:7505:78
    at process.processTicksAndRejections (node:internal/process/task_queues:77:11) {
  code: 14,
  details: 'No connection established. Last error: connect ECONNREFUSED 172.17.0.1:29501 (2025-02-23T18:43:05.164Z)',
  metadata: Metadata { internalRepr: Map(0) {}, options: {} }
}

Node.js v22.4.1

I am trying to learn how to use Nitric so please forgive me if there is an obvious error I am making. From my limited understanding, it looks like the service container builds as expected but then fails to find the nitric gateway during the step where it declares the consumed services, resources, and security through an API to the nitric gateway. I am otherwise not sure what to do next to debug or fix. Any help is greatly appreciated.

[davemooreuws]

Hi @miguelh72,

Thanks for raising this! The issue is caused by Docker-in-Docker when using WSL.

To connect to your host Docker machine, set the NITRIC_DOCKER_HOST environment variable:

NITRIC_DOCKER_HOST=$(ip -4 addr show eth0 | grep -o 'inet [0-9\.]*' | awk '{print $2}') nitric run

This retrieves the correct IP address and sets it before running the command.

We'll update the documentation for WSL.

[miguelh72]

Hi @davemooreuws and thank you for replying with helpful instructions.

I have successfully gotten past the error I previously reported. However, the service doesn't start. When I visit the dashboard at http://localhost:49152/ it just says, "Waiting for your application to start". Perhaps there is something else that is required to get this to work in WSL2? Here is what I get in the terminal:

$ NITRIC_DOCKER_HOST=$(ip -4 addr show eth0 | grep -o 'inet [0-9\.]*' | awk '{print $2}') nitric run
Local cloud started successfully
 build   Building Services.                                                                                        
                                                                                                                   
         hello_services-api complete                                                                               
                                                                                                                   
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│1 services registered with local    │ nitric: started service services/api.ts                               │
│nitric server                       │ services/api.ts:                                                      │
│                                    │                                                                       │
│                                                                                                            │
│                                                                                                            │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 esc: quit ↑/↓: navigate logs

I've tested the same actions I tried initially on a mac and it worked and the API shows up in the dashboard and the terminal includes on left column, api:main - http://localhost:4001, which doesn't show up in WSL2.

Thank you for your time, hopefully this can help others using WSL2 as well.

[davemooreuws]

Hi @miguelh72 ,

I can't reproduce this on Windows 11 with WSL2. I'm using VSCode in WSL2 (Ubuntu 20.04), and it automatically forwards these ports:

What does your project structure and api.ts code look like?
Which package manager are you using (Yarn, npm, etc.)?

Does it work correctly with nitric start?