upstream-zulip/docs/development/setup/wsl-troubleshoot.md

WSL2 users often encounter issues where services fail to start or remain inactive. Follow the steps below to diagnose and resolve such problems.

#### 1. Check the Status of the Service

To verify if a service is running, use the following command:

```console
$ systemctl status <service_name>
```

If the service is inactive, you can attempt to start it with:

```console
$ systemctl start <service_name>
```

#### 2. Diagnose Port Conflicts

Services like `postgresql` may fail to start due to port conflicts. These conflicts can be caused by:

- Other services running in Windows.
- Services running in another WSL2 instance.

#### Resolving Port Conflicts with Other WSL Instances

To resolve port conflicts with another WSL2 instance, stop the conflicting instance using the following command:

```console
> wsl -t <WSL_Instance_Name>
```

After stopping the conflicting instance, restart your WSL instance with:

```console
> wsl -d <Your_Zulip_Instance_Name>
```

#### Resolving Port Conflicts with Services Running on Windows

To resolve conflicts caused by Windows processes:

1. Identify the process using the conflicting port by running:

```console
> Get-Process -Id (Get-NetTCPConnection -LocalPort <your_port_number>).OwningProcess
```

2. If a process is found, terminate it using:

```console
> taskkill /PID <pid> /F
```

3. Restart the Service or Enable Auto-Start

After resolving port conflicts, try restarting the service using:

```console
$ systemctl start <service_name>
```

To ensure the service always starts on boot, enable it with:

```console
$ systemctl enable <service_name>
```

---

#### Additional Tips

- Use `wsl --list` to view all running WSL2 instances and their states.
- Avoid overlapping port usage between WSL2 instances and Windows processes.
- Keep a record of services and their associated port numbers to prevent conflicts in the future.
- Ensure that you use a fresh WSL instance to setup the Zulip development environment to avoid dependency conflicts.