paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-30 19:43:47 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
c1a4dcf33d037d95f1a5665246e87e818ce58864
zulip/docs/development/setup/wsl-troubleshoot.md
apoorvapendse 9912109e82 setup_docs: Add troubleshooting steps for WSL2. 
This commit adds steps to troubleshoot errors encountered
because of certain services like postgresql not starting
on WSL2.

The common reason behind this is port conflicts with other
services running on some other WSL2 instance or the host
Windows system.

This commit provides a guide to handle these issues, and
also provides some additional tips to WSL2 users to avoid
facing these issues in the future.

Fixes #32718.
2025-05-20 10:53:21 -07:00

2.0 KiB
Raw Blame History

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:

$ systemctl status <service_name>

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

$ 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:

> wsl -t <WSL_Instance_Name>

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

> 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:
> Get-Process -Id (Get-NetTCPConnection -LocalPort <your_port_number>).OwningProcess
  1. If a process is found, terminate it using:
> taskkill /PID <pid> /F
  1. Restart the Service or Enable Auto-Start

After resolving port conflicts, try restarting the service using:

$ systemctl start <service_name>

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

$ 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.