Repository: zulip/zulip
Pull request #32719: setup_docs: Add troubleshooting steps for WSL2 services.
Author: login: apoorvapendse
Labels: name: area: documentation (developer)
name: size: XL
name: integration review
description: Added by maintainers when a PR may be ready for integration.
Created: 2024-12-15T02:52:25Z | Merged: 2025-05-20T17:53:21Z

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.

<!-- Describe your pull request here.-->

<!-- If the PR makes UI changes, always include one or more still screenshots to demonstrate your changes. If it seems helpful, add a screen capture of the new functionality as well.

Tooling tips: https://zulip.readthedocs.io/en/latest/tutorials/screenshot-and-gif-software.html
-->

**Screenshots and screen captures:**

*See latest RTD CI build, specifically this page/section: `setup-recommended.html#troubleshooting-and-common-errors`.*

![Screenshot from 2025-05-20 16-04-49](https://github.com/user-attachments/assets/9a6aabd0-c921-4913-ab21-f3bba3b09748)

---

<details>
<summary>Self-review checklist</summary>

<!-- Prior to submitting a PR, follow our step-by-step guide to review your own code:
https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#how-to-review-code -->

<!-- Once you create the PR, check off all the steps below that you have completed.
If any of these steps are not relevant or you have not completed, leave them unchecked.-->

- [x] [Self-reviewed](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#how-to-review-code) the changes for clarity and maintainability
      (variable names, code reuse, readability, etc.).

Communicate decisions, questions, and potential concerns.

- [x] Explains differences from previous plans (e.g., issue description).
- [x] Highlights technical choices and bugs encountered.
- [x] Calls out remaining decisions and concerns.
- [x] Automated tests verify logic where appropriate.

Individual commits are ready for review (see [commit discipline](https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html)).

- [x] Each commit is a coherent idea.
- [x] Commit message(s) explain reasoning and motivation for changes.

Completed manual review and testing of the following:

- [x] Visual appearance of the changes.
- [x] Responsiveness and internationalization.
- [x] Strings and tooltips.
- [x] End-to-end functionality of buttons, interactions and flows.
- [x] Corner cases, error conditions, and easily imagined bugs.
</details>


Linked issue #32718: Troubleshooting steps for WSL2 services.
<!-- Issue description -->
When setting up the Zulip development environment using WSL, new users often encounter issues where essential services, such as PostgreSQL, Redis, or RabbitMQ, fail to start or remain inactive. 

These problems are commonly caused by service misconfigurations, port conflicts with other WSL instances or processes running on Windows, and limitations in the WSL environment. Addressing these issues requires verifying service statuses, resolving port conflicts, and ensuring proper resource allocation. 

This can be particularly challenging for new users unfamiliar with WSL's behavior and service management.

<!-- Link to a message in the chat.zulip.org discussion. Message links will still work even if the topic is renamed or resolved. Link back to this issue from the chat.zulip.org thread. -->

[CZO thread](https://chat.zulip.org/#narrow/channel/21-provision-help/topic/502.20bad.20geteway.3A.20localhost.209991)

Linked issue comments: user: login: Kartikayy007
created_at: 2024-12-15T15:04:43Z
body: @zulipbot claim

author_association: NONE
user: login: zulipbot
created_at: 2024-12-15T15:04:45Z
body: Hello @Kartikayy007!

Thanks for your interest in Zulip! You have attempted to claim an issue without the label "help wanted". You can only claim and submit pull requests for issues with the [help wanted](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+no%3Aassignee+label%3A%22help+wanted%22) label.

If this is your first time here, we recommend reading our [guide for new contributors](https://zulip.readthedocs.io/en/latest/overview/contributing.html) before getting started.

author_association: MEMBER
user: login: Kalpesh-311
created_at: 2024-12-16T17:32:14Z
body: @zulipbot claim

author_association: NONE
user: login: zulipbot
created_at: 2024-12-16T17:32:16Z
body: Hello @Kalpesh-311!

Thanks for your interest in Zulip! You have attempted to claim an issue without the label "help wanted". You can only claim and submit pull requests for issues with the [help wanted](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+no%3Aassignee+label%3A%22help+wanted%22) label.

If this is your first time here, we recommend reading our [guide for new contributors](https://zulip.readthedocs.io/en/latest/overview/contributing.html) before getting started.

author_association: MEMBER
user: login: zulipbot
created_at: 2024-12-16T20:30:32Z
body: Hello @zulip/server-development members, this issue was labeled with the "area: documentation (developer)" label, so you may want to check it out!

<!-- areaLabelAddition -->

author_association: MEMBER

Diff:
diff --git a/docs/development/setup-recommended.md b/docs/development/setup-recommended.md
index cc4813c8e653f..235700b8f2536 100644
--- a/docs/development/setup-recommended.md
+++ b/docs/development/setup-recommended.md
@@ -28,23 +28,6 @@ Contents:
 - [Specifying a proxy](#specifying-a-proxy)
 - [Customizing CPU and RAM allocation](#customizing-cpu-and-ram-allocation)
 
-**If you encounter errors installing the Zulip development
-environment,** check [troubleshooting and common
-errors](#troubleshooting-and-common-errors). If that doesn't help,
-please visit [#provision
-help](https://chat.zulip.org/#narrow/channel/21-provision-help) in the
-[Zulip development community
-server](https://zulip.com/development-community/) for real-time help or
-[file an issue](https://github.com/zulip/zulip/issues).
-
-When reporting your issue, please include the following information:
-
-- host operating system
-- installation method (Vagrant or direct)
-- whether or not you are using a proxy
-- a copy of Zulip's `vagrant` provisioning logs, available in
-  `/var/log/provision.log` on your virtual machine
-
 ### Requirements
 
 Installing the Zulip development environment requires downloading several
@@ -741,9 +724,10 @@ Next, read the following to learn more about developing for Zulip:
 ### Troubleshooting and common errors
 
 Below you'll find a list of common errors and their solutions. Most
-issues are resolved by just provisioning again (by running
-`./tools/provision` (from `/srv/zulip`) inside the Vagrant guest or
-equivalently `vagrant provision` from outside).
+issues are resolved by just provisioning again by running
+`./tools/provision` (from `/srv/zulip`) inside the Vagrant guest (or
+equivalently `vagrant provision` from outside) or by running
+`./tools/provision` in `~/zulip` inside the WSL instance.
 
 If these solutions aren't working for you or you encounter an issue not
 documented below, there are a few ways to get further help:
@@ -754,350 +738,81 @@ documented below, there are a few ways to get further help:
 
 When reporting your issue, please include the following information:
 
-- host operating system
-- installation method (Vagrant or direct)
-- whether or not you are using a proxy
-- a copy of Zulip's `vagrant` provisioning logs, available in
-  `/var/log/provision.log` on your virtual machine. If you choose to
-  post just the error output, please include the **beginning of the
-  error output**, not just the last few lines.
-
-The output of `tools/diagnose` run inside the Vagrant guest is also
-usually helpful.
-
-#### Vagrant guest doesn't show (zulip-server) at start of prompt
-
-This is caused by provisioning failing to complete successfully. You
-can see the errors in `var/log/provision.log`; it should end with
-something like this:
-
-```text
-ESC[94mZulip development environment setup succeeded!ESC[0m
-```
-
-The `ESC` stuff are the terminal color codes that make it show as a nice
-blue in the terminal, which unfortunately looks ugly in the logs.
-
-If you encounter an incomplete `/var/log/provision.log file`, you need to
-update your environment. Re-provision your Vagrant machine; if the problem
-persists, please come chat with us (see instructions above) for help.
-
-After you provision successfully, you'll need to exit your `vagrant ssh`
-shell and run `vagrant ssh` again to get the virtualenv setup properly.
-
-#### Vagrant was unable to mount VirtualBox shared folders
-
-For the following error:
-
-```console
-Vagrant was unable to mount VirtualBox shared folders. This is usually
-because the filesystem "vboxsf" is not available. This filesystem is
-made available via the VirtualBox Guest Additions and kernel
-module. Please verify that these guest additions are properly
-installed in the guest. This is not a bug in Vagrant and is usually
-caused by a faulty Vagrant box. For context, the command attempted
-was:
-
- mount -t vboxsf -o uid=1000,gid=1000 keys /keys
-```
-
-If this error starts happening unexpectedly, then just run:
-
-```console
-$ vagrant halt
-$ vagrant up
-```
-
-to reboot the guest. After this, you can do `vagrant provision` and
-`vagrant ssh`.
-
-#### ssl read error
-
-If you receive the following error while running `vagrant up`:
-
-```console
-SSL read: error:00000000:lib(0):func(0):reason(0), errno 104
-```
-
-It means that either your network connection is unstable and/or very
-slow. To resolve it, run `vagrant up` until it works (possibly on a
-better network connection).
-
-#### Unmet dependencies error
-
-When running `vagrant up` or `provision`, if you see the following error:
-
-```console
-==> default: E:unmet dependencies. Try 'apt-get -f install' with no packages (or specify a solution).
-```
-
-It means that your local apt repository has been corrupted, which can
-usually be resolved by executing the command:
-
-```console
-$ apt-get -f install
-```
-
-#### ssh connection closed by remote host
-
-On running `vagrant ssh`, if you see the following error:
-
-```console
-ssh_exchange_identification: Connection closed by remote host
-```
-
-It usually means the Vagrant guest is not running, which is usually
-solved by rebooting the Vagrant guest via `vagrant halt; vagrant up`. See
-[Vagrant was unable to communicate with the guest machine](#vagrant-was-unable-to-communicate-with-the-guest-machine)
-for more details.
-
-#### os.symlink error
-
-If you receive the following error while running `vagrant up`:
-
-```console
-==> default: Traceback (most recent call last):
-==> default: File "./emoji_dump.py", line 75, in <module>
-==> default:
-==> default: os.symlink('unicode/{}.png'.format(code_point), 'out/{}.png'.format(name))
-==> default: OSError
-==> default: :
-==> default: [Errno 71] Protocol error
-```
-
-Then Vagrant was not able to create a symbolic link.
-
-First, if you are using Windows, **make sure you have run Git BASH (or
-Cygwin) as an administrator**. By default, only administrators can
-create symbolic links on Windows. Additionally [UAC][windows-uac], a
-Windows feature intended to limit the impact of malware, can prevent
-even administrator accounts from creating symlinks. [Turning off
-UAC][disable-uac] will allow you to create symlinks. You can also try
-some of the solutions mentioned
-[here](https://superuser.com/questions/124679/how-do-i-create-a-link-in-windows-7-home-premium-as-a-regular-user).
-
-[windows-uac]: https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/how-user-account-control-works
-[disable-uac]: https://stackoverflow.com/questions/15320550/why-is-secreatesymboliclinkprivilege-ignored-on-windows-8
+- The host operating system
+- The installation method (e.g., Vagrant or WSL)
+- Whether or not you are using a proxy
+- A copy of Zulip's `vagrant` provisioning logs, available in
+  `/var/log/provision.log` on your virtual machine or
+  `~/zulip/var/log/provision.log` on your WSL instance. If you
+  choose to post just the error output, please include the
+  **beginning of the error output**, not just the last few lines.
 
-If you ran Git BASH as administrator but you already had VirtualBox
-running, you might still get this error because VirtualBox is not
-running as administrator. In that case: close the Zulip VM with
-`vagrant halt`; close any other VirtualBox VMs that may be running;
-exit VirtualBox; and try again with `vagrant up --provision` from a
-Git BASH running as administrator.
+The output of `tools/diagnose` (run inside the Vagrant guest or
+WSL instance) is also usually helpful.
 
-Second, VirtualBox does not enable symbolic links by default. Vagrant
-starting with version 1.6.0 enables symbolic links for VirtualBox shared
-folder.
-
-You can check to see that this is enabled for your virtual machine with
-`vboxmanage` command.
-
-Get the name of your virtual machine by running `vboxmanage list vms` and
-then print out the custom settings for this virtual machine with
-`vboxmanage getextradata YOURVMNAME enumerate`:
-
-```console
-$ vboxmanage list vms
-"zulip_default_1462498139595_55484" {5a65199d-8afa-4265-b2f6-6b1f162f157d}
-
-$ vboxmanage getextradata zulip_default_1462498139595_55484 enumerate
-Key: VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip, Value: 1
-Key: supported, Value: false
-```
+::::{tab-set}
 
-If you see "command not found" when you try to run VBoxManage, you need to
-add the VirtualBox directory to your path. On Windows this is mostly likely
-`C:\Program Files\Oracle\VirtualBox\`.
+:::{tab-item} Windows (WSL)
+:sync: os-windows
 
-If `vboxmanage enumerate` prints nothing, or shows a value of 0 for
-VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip, then enable
-symbolic links by running this command in Terminal/Git BASH/Cygwin:
+```{include} setup/wsl-troubleshoot.md
 
-```console
-$ vboxmanage setextradata YOURVMNAME VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip 1
 ```
 
-The virtual machine needs to be shut down when you run this command.
+:::
 
-#### Hyper-V error messages
+:::{tab-item} Windows (VM)
+:sync: os-windows-vm
 
-If you get an error message on Windows about lack of Windows Home
-support for Hyper-V when running `vagrant up`, the problem is that
-Windows is incorrectly attempting to use Hyper-V rather than
-Virtualbox as the virtualization provider. You can fix this by
-explicitly passing the virtualbox provider to `vagrant up`:
+```{include} setup/shared-vagrant-errors.md
 
-```console
-$ vagrant up --provide=virtualbox
 ```
 
-#### Connection timeout on `vagrant up`
+```{include} setup/winvm-troubleshoot.md
 
-If you see the following error after running `vagrant up`:
-
-```console
-default: SSH address: 127.0.0.1:2222
-default: SSH username: vagrant
-default: SSH auth method: private key
-default: Error: Connection timeout. Retrying...
-default: Error: Connection timeout. Retrying...
-default: Error: Connection timeout. Retrying...
 ```
 
-A likely cause is that hardware virtualization is not enabled for your
-computer. This must be done via your computer's BIOS settings. Look for a
-setting called VT-x (Intel) or (AMD-V).
-
-If this is already enabled in your BIOS, double-check that you are running a
-64-bit operating system.
-
-For further information about troubleshooting Vagrant timeout errors [see
-this post](https://stackoverflow.com/questions/22575261/vagrant-stuck-connection-timeout-retrying#22575302).
+:::
 
-#### Vagrant was unable to communicate with the guest machine
+:::{tab-item} macOS
+:sync: os-mac
 
-If you see the following error when you run `vagrant up`:
+```{include} setup/shared-vagrant-errors.md
 
-```console
-Timed out while waiting for the machine to boot. This means that
-Vagrant was unable to communicate with the guest machine within
-the configured ("config.vm.boot_timeout" value) time period.
-
-If you look above, you should be able to see the error(s) that
-Vagrant had when attempting to connect to the machine. These errors
-are usually good hints as to what may be wrong.
-
-If you're using a custom box, make sure that networking is properly
-working and you're able to connect to the machine. It is a common
-problem that networking isn't setup properly in these boxes.
-Verify that authentication configurations are also setup properly,
-as well.
-
-If the box appears to be booting properly, you may want to increase
-the timeout ("config.vm.boot_timeout") value.
 ```
 
-This has a range of possible causes, that usually amount to a bug in
-Virtualbox or Vagrant. If you see this error, you usually can fix it
-by rebooting the guest via `vagrant halt; vagrant up`.
-
-#### Vagrant up fails with subprocess.CalledProcessError
-
-The `vagrant up` command basically does the following:
-
-- Downloads an Ubuntu image and starts it using a Vagrant provider.
-- Uses `vagrant ssh` to connect to that Ubuntu guest, and then runs
-  `tools/provision`, which has a lot of subcommands that are
-  executed via Python's `subprocess` module. These errors mean that
-  one of those subcommands failed.
-
-To debug such errors, you can log in to the Vagrant guest machine by
-running `vagrant ssh`, which should present you with a standard shell
-prompt. You can debug interactively by using, for example,
-`cd zulip && ./tools/provision`, and then running the individual
-subcommands that failed. Once you've resolved the problem, you can
-rerun `tools/provision` to proceed; the provisioning system is
-designed to recover well from failures.
-
-The Zulip provisioning system is generally highly reliable; the most common
-cause of issues here is a poor network connection (or one where you need a
-proxy to access the Internet and haven't [configured the development
-environment to use it](#specifying-a-proxy).
+```{include} setup/unix-troubleshoot.md
 
-Once you've provisioned successfully, you'll get output like this:
-
-```console
-Zulip development environment setup succeeded!
-(zulip-server) vagrant@vagrant:/srv/zulip$
 ```
 
-If the `(zulip-server)` part is missing, this is because your
-installation failed the first time before the Zulip virtualenv was
-created. You can fix this by just closing the shell and running
-`vagrant ssh` again, or using `source .venv/bin/activate`.
-
-Finally, if you encounter any issues that weren't caused by your
-Internet connection, please report them! We try hard to keep Zulip
-development environment provisioning free of bugs.
-
-##### `pip install` fails during `vagrant up` on Linux
-
-Likely causes are:
-
-1. Networking issues
-2. Insufficient RAM. Check whether you've allotted at least two
-   gigabytes of RAM, which is the minimum Zulip
-   [requires](#requirements). If
-   not, go to your VM settings and increase the RAM, then restart
-   the VM.
-
-#### VBoxManage errors related to VT-x or WHvSetupPartition
+:::
 
-```console
-There was an error while executing `VBoxManage`, a CLI used by Vagrant
-for controlling VirtualBox. The command and stderr is shown below.
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
 
-Command: ["startvm", "8924a681-b4e4-4b7a-96f2-4cb11619f123", "--type", "headless"]
+```{include} setup/shared-vagrant-errors.md
 
-Stderr: VBoxManage.exe: error: (VERR_NEM_MISSING_KERNEL_API).
-VBoxManage.exe: error: VT-x is not available (VERR_VMX_NO_VMX)
-VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component ConsoleWrap, interface IConsole
 ```
 
-or
+```{include} setup/unix-troubleshoot.md
 
-```console
-Stderr: VBoxManage.exe: error: Call to WHvSetupPartition failed: ERROR_SUCCESS (Last=0xc000000d/87) (VERR_NEM_VM_CREATE_FAILED)
-VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component ConsoleWrap, interface IConsole
 ```
 
-First, ensure that hardware virtualization support (VT-x or AMD-V) is
-enabled in your BIOS.
-
-If the error persists, you may have run into an incompatibility
-between VirtualBox and Hyper-V on Windows. To disable Hyper-V, open
-command prompt as administrator, run
-`bcdedit /set hypervisorlaunchtype off`, and reboot. If you need to
-enable it later, run `bcdedit /deletevalue hypervisorlaunchtype`, and
-reboot.
-
-#### OSError: [Errno 26] Text file busy
+:::
 
-```console
-default: Traceback (most recent call last):
-…
-default:   File "/srv/zulip-py3-venv/lib/python3.6/shutil.py", line 426, in _rmtree_safe_fd
-default:     os.rmdir(name, dir_fd=topfd)
-default: OSError: [Errno 26] Text file busy: 'baremetrics'
-```
+:::{tab-item} Fedora
+:sync: os-fedora
 
-This error is caused by a
-[bug](https://www.virtualbox.org/ticket/19004) in recent versions of
-the VirtualBox Guest Additions for Linux on Windows hosts. You can
-check the running version of VirtualBox Guest Additions with this
-command:
+```{include} setup/shared-vagrant-errors.md
 
-```console
-$ vagrant ssh -- 'sudo modinfo -F version vboxsf'
 ```
 
-The bug has not been fixed upstream as of this writing, but you may be
-able to work around it by downgrading VirtualBox Guest Additions to
-5.2.44. To do this, create a `~/.zulip-vagrant-config` file and add
-this line:
+```{include} setup/unix-troubleshoot.md
 
-```text
-VBOXADD_VERSION 5.2.44
 ```
 
-Then run these commands (yes, reload is needed twice):
-
-```console
-$ vagrant plugin install vagrant-vbguest
-$ vagrant reload
-$ vagrant reload --provision
-```
+:::
+::::
 
 ### Specifying an Ubuntu mirror
 
diff --git a/docs/development/setup/shared-vagrant-errors.md b/docs/development/setup/shared-vagrant-errors.md
new file mode 100644
index 0000000000000..80964a2a44ee1
--- /dev/null
+++ b/docs/development/setup/shared-vagrant-errors.md
@@ -0,0 +1,121 @@
+#### Vagrant guest doesn't show (zulip-server) at start of prompt
+
+This is caused by provisioning failing to complete successfully. You
+can see the errors in `var/log/provision.log`; it should end with
+something like this:
+
+```text
+ESC[94mZulip development environment setup succeeded!ESC[0m
+```
+
+The `ESC` stuff are the terminal color codes that make it show as a nice
+blue in the terminal, which unfortunately looks ugly in the logs.
+
+If you encounter an incomplete `/var/log/provision.log file`, you need to
+update your environment. Re-provision your Vagrant machine; if the problem
+persists, please come chat with us (see instructions above) for help.
+
+After you provision successfully, you'll need to exit your `vagrant ssh`
+shell and run `vagrant ssh` again to get the virtualenv setup properly.
+
+#### ssl read error
+
+If you receive the following error while running `vagrant up`:
+
+```console
+SSL read: error:00000000:lib(0):func(0):reason(0), errno 104
+```
+
+It means that either your network connection is unstable and/or very
+slow. To resolve it, run `vagrant up` until it works (possibly on a
+better network connection).
+
+#### ssh connection closed by remote host
+
+On running `vagrant ssh`, if you see the following error:
+
+```console
+ssh_exchange_identification: Connection closed by remote host
+```
+
+It usually means the Vagrant guest is not running, which is usually
+solved by rebooting the Vagrant guest via `vagrant halt; vagrant up`. See
+[Vagrant was unable to communicate with the guest machine](/development/setup-recommended.md#vagrant-was-unable-to-communicate-with-the-guest-machine)
+for more details.
+
+#### Vagrant was unable to communicate with the guest machine
+
+If you see the following error when you run `vagrant up`:
+
+```console
+Timed out while waiting for the machine to boot. This means that
+Vagrant was unable to communicate with the guest machine within
+the configured ("config.vm.boot_timeout" value) time period.
+
+If you look above, you should be able to see the error(s) that
+Vagrant had when attempting to connect to the machine. These errors
+are usually good hints as to what may be wrong.
+
+If you're using a custom box, make sure that networking is properly
+working and you're able to connect to the machine. It is a common
+problem that networking isn't setup properly in these boxes.
+Verify that authentication configurations are also setup properly,
+as well.
+
+If the box appears to be booting properly, you may want to increase
+the timeout ("config.vm.boot_timeout") value.
+```
+
+This has a range of possible causes, that usually amount to a bug in
+Virtualbox or Vagrant. If you see this error, you usually can fix it
+by rebooting the guest via `vagrant halt; vagrant up`.
+
+#### Vagrant up fails with subprocess.CalledProcessError
+
+The `vagrant up` command basically does the following:
+
+- Downloads an Ubuntu image and starts it using a Vagrant provider.
+- Uses `vagrant ssh` to connect to that Ubuntu guest, and then runs
+  `tools/provision`, which has a lot of subcommands that are
+  executed via Python's `subprocess` module. These errors mean that
+  one of those subcommands failed.
+
+To debug such errors, you can log in to the Vagrant guest machine by
+running `vagrant ssh`, which should present you with a standard shell
+prompt. You can debug interactively by using, for example,
+`cd zulip && ./tools/provision`, and then running the individual
+subcommands that failed. Once you've resolved the problem, you can
+rerun `tools/provision` to proceed; the provisioning system is
+designed to recover well from failures.
+
+The Zulip provisioning system is generally highly reliable; the most common
+cause of issues here is a poor network connection (or one where you need a
+proxy to access the Internet and haven't [configured the development
+environment to use it](/development/setup-recommended.md#specifying-a-proxy)).
+
+Once you've provisioned successfully, you'll get output like this:
+
+```console
+Zulip development environment setup succeeded!
+(zulip-server) vagrant@vagrant:/srv/zulip$
+```
+
+If the `(zulip-server)` part is missing, this is because your
+installation failed the first time before the Zulip virtualenv was
+created. You can fix this by just closing the shell and running
+`vagrant ssh` again, or using `source .venv/bin/activate`.
+
+Finally, if you encounter any issues that weren't caused by your
+Internet connection, please report them! We try hard to keep Zulip
+development environment provisioning free of bugs.
+
+##### `pip install` fails during `vagrant up` on Linux
+
+Likely causes are:
+
+1. Networking issues
+2. Insufficient RAM. Check whether you've allotted at least two
+   gigabytes of RAM, which is the minimum Zulip
+   [requires](/development/setup-recommended.md#requirements). If
+   not, go to your VM settings and increase the RAM, then restart
+   the VM.
diff --git a/docs/development/setup/unix-troubleshoot.md b/docs/development/setup/unix-troubleshoot.md
new file mode 100644
index 0000000000000..7130d08664580
--- /dev/null
+++ b/docs/development/setup/unix-troubleshoot.md
@@ -0,0 +1,14 @@
+#### Unmet dependencies error
+
+When running `vagrant up` or `provision`, if you see the following error:
+
+```console
+==> default: E:unmet dependencies. Try 'apt-get -f install' with no packages (or specify a solution).
+```
+
+It means that your local apt repository has been corrupted, which can
+usually be resolved by executing the command:
+
+```console
+$ apt-get -f install
+```
diff --git a/docs/development/setup/winvm-troubleshoot.md b/docs/development/setup/winvm-troubleshoot.md
new file mode 100644
index 0000000000000..8678f82f1d152
--- /dev/null
+++ b/docs/development/setup/winvm-troubleshoot.md
@@ -0,0 +1,196 @@
+#### Vagrant was unable to mount VirtualBox shared folders
+
+For the following error:
+
+```console
+Vagrant was unable to mount VirtualBox shared folders. This is usually
+because the filesystem "vboxsf" is not available. This filesystem is
+made available via the VirtualBox Guest Additions and kernel
+module. Please verify that these guest additions are properly
+installed in the guest. This is not a bug in Vagrant and is usually
+caused by a faulty Vagrant box. For context, the command attempted
+was:
+
+ mount -t vboxsf -o uid=1000,gid=1000 keys /keys
+```
+
+If this error starts happening unexpectedly, then just run:
+
+```console
+$ vagrant halt
+$ vagrant up
+```
+
+to reboot the guest. After this, you can do `vagrant provision` and
+`vagrant ssh`.
+
+#### os.symlink error
+
+If you receive the following error while running `vagrant up`:
+
+```console
+==> default: Traceback (most recent call last):
+==> default: File "./emoji_dump.py", line 75, in <module>
+==> default:
+==> default: os.symlink('unicode/{}.png'.format(code_point), 'out/{}.png'.format(name))
+==> default: OSError
+==> default: :
+==> default: [Errno 71] Protocol error
+```
+
+Then Vagrant was not able to create a symbolic link.
+
+First, if you are using Windows, **make sure you have run Git BASH (or
+Cygwin) as an administrator**. By default, only administrators can
+create symbolic links on Windows. Additionally [UAC][windows-uac], a
+Windows feature intended to limit the impact of malware, can prevent
+even administrator accounts from creating symlinks. [Turning off
+UAC][disable-uac] will allow you to create symlinks. You can also try
+some of the solutions mentioned
+[here](https://superuser.com/questions/124679/how-do-i-create-a-link-in-windows-7-home-premium-as-a-regular-user).
+
+[windows-uac]: https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/how-user-account-control-works
+[disable-uac]: https://stackoverflow.com/questions/15320550/why-is-secreatesymboliclinkprivilege-ignored-on-windows-8
+
+If you ran Git BASH as administrator but you already had VirtualBox
+running, you might still get this error because VirtualBox is not
+running as administrator. In that case: close the Zulip VM with
+`vagrant halt`; close any other VirtualBox VMs that may be running;
+exit VirtualBox; and try again with `vagrant up --provision` from a
+Git BASH running as administrator.
+
+Second, VirtualBox does not enable symbolic links by default. Vagrant
+starting with version 1.6.0 enables symbolic links for VirtualBox shared
+folder.
+
+You can check to see that this is enabled for your virtual machine with
+`vboxmanage` command.
+
+Get the name of your virtual machine by running `vboxmanage list vms` and
+then print out the custom settings for this virtual machine with
+`vboxmanage getextradata YOURVMNAME enumerate`:
+
+```console
+$ vboxmanage list vms
+"zulip_default_1462498139595_55484" {5a65199d-8afa-4265-b2f6-6b1f162f157d}
+
+$ vboxmanage getextradata zulip_default_1462498139595_55484 enumerate
+Key: VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip, Value: 1
+Key: supported, Value: false
+```
+
+If you see "command not found" when you try to run VBoxManage, you need to
+add the VirtualBox directory to your path. On Windows this is mostly likely
+`C:\Program Files\Oracle\VirtualBox\`.
+
+If `vboxmanage enumerate` prints nothing, or shows a value of 0 for
+VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip, then enable
+symbolic links by running this command in Terminal/Git BASH/Cygwin:
+
+```console
+$ vboxmanage setextradata YOURVMNAME VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip 1
+```
+
+The virtual machine needs to be shut down when you run this command.
+
+#### Hyper-V error messages
+
+If you get an error message on Windows about lack of Windows Home
+support for Hyper-V when running `vagrant up`, the problem is that
+Windows is incorrectly attempting to use Hyper-V rather than
+Virtualbox as the virtualization provider. You can fix this by
+explicitly passing the virtualbox provider to `vagrant up`:
+
+```console
+$ vagrant up --provide=virtualbox
+```
+
+#### Connection timeout on `vagrant up`
+
+If you see the following error after running `vagrant up`:
+
+```console
+default: SSH address: 127.0.0.1:2222
+default: SSH username: vagrant
+default: SSH auth method: private key
+default: Error: Connection timeout. Retrying...
+default: Error: Connection timeout. Retrying...
+default: Error: Connection timeout. Retrying...
+```
+
+A likely cause is that hardware virtualization is not enabled for your
+computer. This must be done via your computer's BIOS settings. Look for a
+setting called VT-x (Intel) or (AMD-V).
+
+If this is already enabled in your BIOS, double-check that you are running a
+64-bit operating system.
+
+For further information about troubleshooting Vagrant timeout errors [see
+this post](https://stackoverflow.com/questions/22575261/vagrant-stuck-connection-timeout-retrying#22575302).
+
+#### VBoxManage errors related to VT-x or WHvSetupPartition
+
+```console
+There was an error while executing `VBoxManage`, a CLI used by Vagrant
+for controlling VirtualBox. The command and stderr is shown below.
+
+Command: ["startvm", "8924a681-b4e4-4b7a-96f2-4cb11619f123", "--type", "headless"]
+
+Stderr: VBoxManage.exe: error: (VERR_NEM_MISSING_KERNEL_API).
+VBoxManage.exe: error: VT-x is not available (VERR_VMX_NO_VMX)
+VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component ConsoleWrap, interface IConsole
+```
+
+or
+
+```console
+Stderr: VBoxManage.exe: error: Call to WHvSetupPartition failed: ERROR_SUCCESS (Last=0xc000000d/87) (VERR_NEM_VM_CREATE_FAILED)
+VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component ConsoleWrap, interface IConsole
+```
+
+First, ensure that hardware virtualization support (VT-x or AMD-V) is
+enabled in your BIOS.
+
+If the error persists, you may have run into an incompatibility
+between VirtualBox and Hyper-V on Windows. To disable Hyper-V, open
+command prompt as administrator, run
+`bcdedit /set hypervisorlaunchtype off`, and reboot. If you need to
+enable it later, run `bcdedit /deletevalue hypervisorlaunchtype`, and
+reboot.
+
+#### OSError: [Errno 26] Text file busy
+
+```console
+default: Traceback (most recent call last):
+…
+default:   File "/srv/zulip-py3-venv/lib/python3.6/shutil.py", line 426, in _rmtree_safe_fd
+default:     os.rmdir(name, dir_fd=topfd)
+default: OSError: [Errno 26] Text file busy: 'baremetrics'
+```
+
+This error is caused by a
+[bug](https://www.virtualbox.org/ticket/19004) in recent versions of
+the VirtualBox Guest Additions for Linux on Windows hosts. You can
+check the running version of VirtualBox Guest Additions with this
+command:
+
+```console
+$ vagrant ssh -- 'sudo modinfo -F version vboxsf'
+```
+
+The bug has not been fixed upstream as of this writing, but you may be
+able to work around it by downgrading VirtualBox Guest Additions to
+5.2.44. To do this, create a `~/.zulip-vagrant-config` file and add
+this line:
+
+```text
+VBOXADD_VERSION 5.2.44
+```
+
+Then run these commands (yes, reload is needed twice):
+
+```console
+$ vagrant plugin install vagrant-vbguest
+$ vagrant reload
+$ vagrant reload --provision
+```
diff --git a/docs/development/setup/wsl-troubleshoot.md b/docs/development/setup/wsl-troubleshoot.md
new file mode 100644
index 0000000000000..12697a57b21ce
--- /dev/null
+++ b/docs/development/setup/wsl-troubleshoot.md
@@ -0,0 +1,75 @@
+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.


Reviews:
user: login: Kalpesh-311
state: APPROVED
author_association: NONE
submitted_at: 2024-12-16T19:52:44Z
user: login: laurynmm
body: @apoorvapendse - Thanks for working on improving this documentation! I had a few thoughts on how we can make these changes more maintainable. Let me know if you have any questions about my comments.

For future reviews, it could be helpful to structure your changes in smaller chunks as it was hard for me to see the updates you'd made to the Windows errors documentation you made in the first commit.

I might do something like this...
1. Update the intro text to work for both WSL and Vagrant (see my comment below).
2. Create the shared-errors file, and include it in the non-tab version. So, it's clear here that there's no content changes, just moving the text to separate files.
3. Pull out the errors into the three files - shared, vagrant and winvm. That way it's clear what's unique, specific for Windows/Vagrant and shared for all systems. And you'd add the tabs at this point.
5. Add the Windows WSL2 tab and the wsl-troubleshoot file with any specific errors for that tab, and including any of the previously shared files there as well.
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-09T15:44:33Z
user: login: apoorvapendse
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-11T04:40:50Z
user: login: laurynmm
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-20T13:58:29Z

Review comments:
diff_hunk: @@ -740,485 +740,44 @@ Next, read the following to learn more about developing for Zulip:
 
 ### Troubleshooting and common errors
 
-Below you'll find a list of common errors and their solutions. Most
-issues are resolved by just provisioning again (by running
-`./tools/provision` (from `/srv/zulip`) inside the Vagrant guest or
-equivalently `vagrant provision` from outside).
path: docs/development/setup-recommended.md
user: login: laurynmm
body: Let's have a shared intro section here before the tabs. In places where we mention Vagrant, we can add "or WSL instance" or something equivalent.
created_at: 2025-05-09T15:25:05Z
author_association: COLLABORATOR
diff_hunk: @@ -740,485 +740,44 @@ Next, read the following to learn more about developing for Zulip:
 
 ### Troubleshooting and common errors
 
-Below you'll find a list of common errors and their solutions. Most
-issues are resolved by just provisioning again (by running
-`./tools/provision` (from `/srv/zulip`) inside the Vagrant guest or
-equivalently `vagrant provision` from outside).
-
-If these solutions aren't working for you or you encounter an issue not
-documented below, there are a few ways to get further help:
-
-- Ask in [#provision help](https://chat.zulip.org/#narrow/channel/21-provision-help)
-  in the [Zulip development community server](https://zulip.com/development-community/).
-- [File an issue](https://github.com/zulip/zulip/issues).
-
-When reporting your issue, please include the following information:
-
-- host operating system
-- installation method (Vagrant or direct)
-- whether or not you are using a proxy
-- a copy of Zulip's `vagrant` provisioning logs, available in
path: docs/development/setup-recommended.md
user: login: laurynmm
body: Let's have this list start with capital letters.
created_at: 2025-05-09T15:25:25Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,478 @@
+Below you'll find a list of common errors and their solutions. Most
+issues are resolved by just provisioning again (by running
+`./tools/provision` (from `/srv/zulip`) inside the Vagrant guest or
+equivalently `vagrant provision` from outside).
+
+If these solutions aren't working for you or you encounter an issue not
+documented below, there are a few ways to get further help:
+
+- Ask in [#provision help](https://chat.zulip.org/#narrow/channel/21-provision-help)
+  in the [Zulip development community server](https://zulip.com/development-community/).
+- [File an issue](https://github.com/zulip/zulip/issues).
+
+When reporting your issue, please include the following information:
+
+- host operating system
+- installation method (Vagrant or direct)
+- whether or not you are using a proxy
+- a copy of Zulip's `vagrant` provisioning logs, available in
+  `/var/log/provision.log` on your virtual machine. If you choose to
+  post just the error output, please include the **beginning of the
+  error output**, not just the last few lines.
+
+The output of `tools/diagnose` run inside the Vagrant guest is also
+usually helpful.
+
+#### Vagrant guest doesn't show (zulip-py3-venv) at start of prompt
+
+This is caused by provisioning failing to complete successfully. You
+can see the errors in `var/log/provision.log`; it should end with
+something like this:
path: docs/development/setup/winvm-troubleshoot.md
user: login: laurynmm
body: Any section that's 100% duplicated here form the vagrant-troubleshoot doc, should be in a shared errors file. That way we're not creating a situation where we have to update the same text in multiple files for maintaining this documentation. 

Any any section that's unique or different for Windows / Vagrant systems, would be in a separate file. So your tabs in  setup-recommended would be something like ...

````markdown
::::{tab-set}

:::{tab-item} Windows (VM)

```{include} setup/shared-errors-troubleshoot.md

```

```{include} setup/winvm-troubleshoot.md

```

:::

:::{tab-item} macOS
:sync: os-mac

```{include} setup/shared-errors-troubleshoot.md

```

```{include} setup/vagrant-troubleshoot.md

```
````
created_at: 2025-05-09T15:30:50Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,121 @@
+#### Vagrant guest doesn't show (zulip-server) at start of prompt
+
+This is caused by provisioning failing to complete successfully. You
+can see the errors in `var/log/provision.log`; it should end with
+something like this:
+
+```text
+ESC[94mZulip development environment setup succeeded!ESC[0m
+```
+
+The `ESC` stuff are the terminal color codes that make it show as a nice
+blue in the terminal, which unfortunately looks ugly in the logs.
+
+If you encounter an incomplete `/var/log/provision.log file`, you need to
+update your environment. Re-provision your Vagrant machine; if the problem
+persists, please come chat with us (see instructions above) for help.
+
+After you provision successfully, you'll need to exit your `vagrant ssh`
+shell and run `vagrant ssh` again to get the virtualenv setup properly.
+
+#### ssl read error
+
+If you receive the following error while running `vagrant up`:
+
+```console
+SSL read: error:00000000:lib(0):func(0):reason(0), errno 104
+```
+
+It means that either your network connection is unstable and/or very
+slow. To resolve it, run `vagrant up` until it works (possibly on a
+better network connection).
+
+#### ssh connection closed by remote host
+
+On running `vagrant ssh`, if you see the following error:
+
+```console
+ssh_exchange_identification: Connection closed by remote host
+```
+
+It usually means the Vagrant guest is not running, which is usually
+solved by rebooting the Vagrant guest via `vagrant halt; vagrant up`. See
+[Vagrant was unable to communicate with the guest machine](#vagrant-was-unable-to-communicate-with-the-guest-machine)
+for more details.
+
+#### Vagrant was unable to communicate with the guest machine
+
+If you see the following error when you run `vagrant up`:
+
+```console
+Timed out while waiting for the machine to boot. This means that
+Vagrant was unable to communicate with the guest machine within
+the configured ("config.vm.boot_timeout" value) time period.
+
+If you look above, you should be able to see the error(s) that
+Vagrant had when attempting to connect to the machine. These errors
+are usually good hints as to what may be wrong.
+
+If you're using a custom box, make sure that networking is properly
+working and you're able to connect to the machine. It is a common
+problem that networking isn't setup properly in these boxes.
+Verify that authentication configurations are also setup properly,
+as well.
+
+If the box appears to be booting properly, you may want to increase
+the timeout ("config.vm.boot_timeout") value.
+```
+
+This has a range of possible causes, that usually amount to a bug in
+Virtualbox or Vagrant. If you see this error, you usually can fix it
+by rebooting the guest via `vagrant halt; vagrant up`.
+
+#### Vagrant up fails with subprocess.CalledProcessError
+
+The `vagrant up` command basically does the following:
+
+- Downloads an Ubuntu image and starts it using a Vagrant provider.
+- Uses `vagrant ssh` to connect to that Ubuntu guest, and then runs
+  `tools/provision`, which has a lot of subcommands that are
+  executed via Python's `subprocess` module. These errors mean that
+  one of those subcommands failed.
+
+To debug such errors, you can log in to the Vagrant guest machine by
+running `vagrant ssh`, which should present you with a standard shell
+prompt. You can debug interactively by using, for example,
+`cd zulip && ./tools/provision`, and then running the individual
+subcommands that failed. Once you've resolved the problem, you can
+rerun `tools/provision` to proceed; the provisioning system is
+designed to recover well from failures.
+
+The Zulip provisioning system is generally highly reliable; the most common
+cause of issues here is a poor network connection (or one where you need a
+proxy to access the Internet and haven't [configured the development
+environment to use it](#specifying-a-proxy).
+
+Once you've provisioned successfully, you'll get output like this:
+
+```console
+Zulip development environment setup succeeded!
+(zulip-server) vagrant@vagrant:/srv/zulip$
+```
+
+If the `(zulip-server)` part is missing, this is because your
+installation failed the first time before the Zulip virtualenv was
+created. You can fix this by just closing the shell and running
+`vagrant ssh` again, or using `source .venv/bin/activate`.
+
+Finally, if you encounter any issues that weren't caused by your
+Internet connection, please report them! We try hard to keep Zulip
+development environment provisioning free of bugs.
+
+##### `pip install` fails during `vagrant up` on Linux
+
path: docs/development/setup/shared-vagrant-errors.md
user: login: apoorvapendse
body: I don't think this is Linux specific, which is why I included it in the shared errors file. Should we omit "on Linux"?
created_at: 2025-05-11T04:39:33Z
author_association: COLLABORATOR
diff_hunk: @@ -754,350 +738,81 @@ documented below, there are a few ways to get further help:
 
 When reporting your issue, please include the following information:
 
-- host operating system
-- installation method (Vagrant or direct)
-- whether or not you are using a proxy
-- a copy of Zulip's `vagrant` provisioning logs, available in
-  `/var/log/provision.log` on your virtual machine. If you choose to
+- Host operating system
+- Installation method (Vagrant or direct(like using WSL))
+- Whether or not you are using a proxy
+- A copy of Zulip's `vagrant` provisioning logs, available in
+  `/var/log/provision.log` on your virtual machine or `~/zulip/var/log/provision.log`
+  on your WSL instance. If you choose to
   post just the error output, please include the **beginning of the
   error output**, not just the last few lines.
 
-The output of `tools/diagnose` run inside the Vagrant guest is also
+The output of `tools/diagnose` run inside the Vagrant guest or WSL instance is also
 usually helpful.
 
-#### Vagrant guest doesn't show (zulip-server) at start of prompt
-
-This is caused by provisioning failing to complete successfully. You
-can see the errors in `var/log/provision.log`; it should end with
-something like this:
-
-```text
-ESC[94mZulip development environment setup succeeded!ESC[0m
-```
-
-The `ESC` stuff are the terminal color codes that make it show as a nice
-blue in the terminal, which unfortunately looks ugly in the logs.
-
-If you encounter an incomplete `/var/log/provision.log file`, you need to
-update your environment. Re-provision your Vagrant machine; if the problem
-persists, please come chat with us (see instructions above) for help.
-
-After you provision successfully, you'll need to exit your `vagrant ssh`
-shell and run `vagrant ssh` again to get the virtualenv setup properly.
-
-#### Vagrant was unable to mount VirtualBox shared folders
-
-For the following error:
-
-```console
-Vagrant was unable to mount VirtualBox shared folders. This is usually
-because the filesystem "vboxsf" is not available. This filesystem is
-made available via the VirtualBox Guest Additions and kernel
-module. Please verify that these guest additions are properly
-installed in the guest. This is not a bug in Vagrant and is usually
-caused by a faulty Vagrant box. For context, the command attempted
-was:
-
- mount -t vboxsf -o uid=1000,gid=1000 keys /keys
-```
-
-If this error starts happening unexpectedly, then just run:
-
-```console
-$ vagrant halt
-$ vagrant up
-```
-
-to reboot the guest. After this, you can do `vagrant provision` and
-`vagrant ssh`.
-
-#### ssl read error
-
-If you receive the following error while running `vagrant up`:
-
-```console
-SSL read: error:00000000:lib(0):func(0):reason(0), errno 104
-```
-
-It means that either your network connection is unstable and/or very
-slow. To resolve it, run `vagrant up` until it works (possibly on a
-better network connection).
-
-#### Unmet dependencies error
-
-When running `vagrant up` or `provision`, if you see the following error:
-
-```console
-==> default: E:unmet dependencies. Try 'apt-get -f install' with no packages (or specify a solution).
-```
-
-It means that your local apt repository has been corrupted, which can
-usually be resolved by executing the command:
-
-```console
-$ apt-get -f install
-```
-
-#### ssh connection closed by remote host
-
-On running `vagrant ssh`, if you see the following error:
-
-```console
-ssh_exchange_identification: Connection closed by remote host
-```
-
-It usually means the Vagrant guest is not running, which is usually
-solved by rebooting the Vagrant guest via `vagrant halt; vagrant up`. See
-[Vagrant was unable to communicate with the guest machine](#vagrant-was-unable-to-communicate-with-the-guest-machine)
-for more details.
-
-#### os.symlink error
-
-If you receive the following error while running `vagrant up`:
-
-```console
-==> default: Traceback (most recent call last):
-==> default: File "./emoji_dump.py", line 75, in <module>
-==> default:
-==> default: os.symlink('unicode/{}.png'.format(code_point), 'out/{}.png'.format(name))
-==> default: OSError
-==> default: :
-==> default: [Errno 71] Protocol error
-```
-
-Then Vagrant was not able to create a symbolic link.
-
-First, if you are using Windows, **make sure you have run Git BASH (or
-Cygwin) as an administrator**. By default, only administrators can
-create symbolic links on Windows. Additionally [UAC][windows-uac], a
-Windows feature intended to limit the impact of malware, can prevent
-even administrator accounts from creating symlinks. [Turning off
-UAC][disable-uac] will allow you to create symlinks. You can also try
-some of the solutions mentioned
-[here](https://superuser.com/questions/124679/how-do-i-create-a-link-in-windows-7-home-premium-as-a-regular-user).
-
-[windows-uac]: https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/how-user-account-control-works
-[disable-uac]: https://stackoverflow.com/questions/15320550/why-is-secreatesymboliclinkprivilege-ignored-on-windows-8
-
-If you ran Git BASH as administrator but you already had VirtualBox
-running, you might still get this error because VirtualBox is not
-running as administrator. In that case: close the Zulip VM with
-`vagrant halt`; close any other VirtualBox VMs that may be running;
-exit VirtualBox; and try again with `vagrant up --provision` from a
-Git BASH running as administrator.
-
-Second, VirtualBox does not enable symbolic links by default. Vagrant
-starting with version 1.6.0 enables symbolic links for VirtualBox shared
-folder.
-
-You can check to see that this is enabled for your virtual machine with
-`vboxmanage` command.
-
-Get the name of your virtual machine by running `vboxmanage list vms` and
-then print out the custom settings for this virtual machine with
-`vboxmanage getextradata YOURVMNAME enumerate`:
-
-```console
-$ vboxmanage list vms
-"zulip_default_1462498139595_55484" {5a65199d-8afa-4265-b2f6-6b1f162f157d}
-
-$ vboxmanage getextradata zulip_default_1462498139595_55484 enumerate
-Key: VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip, Value: 1
-Key: supported, Value: false
-```
+::::{tab-set}
 
-If you see "command not found" when you try to run VBoxManage, you need to
-add the VirtualBox directory to your path. On Windows this is mostly likely
-`C:\Program Files\Oracle\VirtualBox\`.
+:::{tab-item} Windows (WSL)
+:sync: os-windows
 
-If `vboxmanage enumerate` prints nothing, or shows a value of 0 for
-VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip, then enable
-symbolic links by running this command in Terminal/Git BASH/Cygwin:
+```{include} setup/wsl-troubleshoot.md
 
-```console
-$ vboxmanage setextradata YOURVMNAME VBoxInternal2/SharedFoldersEnableSymlinksCreate/srv_zulip 1
 ```
 
-The virtual machine needs to be shut down when you run this command.
+:::
 
-#### Hyper-V error messages
+:::{tab-item} Windows (VM)
+:sync: os-windows-vm
 
-If you get an error message on Windows about lack of Windows Home
-support for Hyper-V when running `vagrant up`, the problem is that
-Windows is incorrectly attempting to use Hyper-V rather than
-Virtualbox as the virtualization provider. You can fix this by
-explicitly passing the virtualbox provider to `vagrant up`:
+```{include} setup/shared-vagrant-errors.md
 
-```console
-$ vagrant up --provide=virtualbox
 ```
 
-#### Connection timeout on `vagrant up`
+```{include} setup/winvm-troubleshoot.md
 
path: docs/development/setup-recommended.md
user: login: apoorvapendse
body: My assumption here is that we will use vbox as the provider only for Windows.

created_at: 2025-05-11T04:40:45Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,121 @@
+#### Vagrant guest doesn't show (zulip-server) at start of prompt
+
+This is caused by provisioning failing to complete successfully. You
+can see the errors in `var/log/provision.log`; it should end with
+something like this:
+
+```text
+ESC[94mZulip development environment setup succeeded!ESC[0m
+```
+
+The `ESC` stuff are the terminal color codes that make it show as a nice
+blue in the terminal, which unfortunately looks ugly in the logs.
+
+If you encounter an incomplete `/var/log/provision.log file`, you need to
+update your environment. Re-provision your Vagrant machine; if the problem
+persists, please come chat with us (see instructions above) for help.
+
+After you provision successfully, you'll need to exit your `vagrant ssh`
+shell and run `vagrant ssh` again to get the virtualenv setup properly.
+
+#### ssl read error
+
+If you receive the following error while running `vagrant up`:
+
+```console
+SSL read: error:00000000:lib(0):func(0):reason(0), errno 104
+```
+
+It means that either your network connection is unstable and/or very
+slow. To resolve it, run `vagrant up` until it works (possibly on a
+better network connection).
+
+#### ssh connection closed by remote host
+
+On running `vagrant ssh`, if you see the following error:
+
+```console
+ssh_exchange_identification: Connection closed by remote host
+```
+
+It usually means the Vagrant guest is not running, which is usually
+solved by rebooting the Vagrant guest via `vagrant halt; vagrant up`. See
+[Vagrant was unable to communicate with the guest machine](#vagrant-was-unable-to-communicate-with-the-guest-machine)
+for more details.
+
+#### Vagrant was unable to communicate with the guest machine
+
+If you see the following error when you run `vagrant up`:
+
+```console
+Timed out while waiting for the machine to boot. This means that
+Vagrant was unable to communicate with the guest machine within
+the configured ("config.vm.boot_timeout" value) time period.
+
+If you look above, you should be able to see the error(s) that
+Vagrant had when attempting to connect to the machine. These errors
+are usually good hints as to what may be wrong.
+
+If you're using a custom box, make sure that networking is properly
+working and you're able to connect to the machine. It is a common
+problem that networking isn't setup properly in these boxes.
+Verify that authentication configurations are also setup properly,
+as well.
+
+If the box appears to be booting properly, you may want to increase
+the timeout ("config.vm.boot_timeout") value.
+```
+
+This has a range of possible causes, that usually amount to a bug in
+Virtualbox or Vagrant. If you see this error, you usually can fix it
+by rebooting the guest via `vagrant halt; vagrant up`.
+
+#### Vagrant up fails with subprocess.CalledProcessError
+
+The `vagrant up` command basically does the following:
+
+- Downloads an Ubuntu image and starts it using a Vagrant provider.
+- Uses `vagrant ssh` to connect to that Ubuntu guest, and then runs
+  `tools/provision`, which has a lot of subcommands that are
+  executed via Python's `subprocess` module. These errors mean that
+  one of those subcommands failed.
+
+To debug such errors, you can log in to the Vagrant guest machine by
+running `vagrant ssh`, which should present you with a standard shell
+prompt. You can debug interactively by using, for example,
+`cd zulip && ./tools/provision`, and then running the individual
+subcommands that failed. Once you've resolved the problem, you can
+rerun `tools/provision` to proceed; the provisioning system is
+designed to recover well from failures.
+
+The Zulip provisioning system is generally highly reliable; the most common
+cause of issues here is a poor network connection (or one where you need a
+proxy to access the Internet and haven't [configured the development
+environment to use it](#specifying-a-proxy).
+
+Once you've provisioned successfully, you'll get output like this:
+
+```console
+Zulip development environment setup succeeded!
+(zulip-server) vagrant@vagrant:/srv/zulip$
+```
+
+If the `(zulip-server)` part is missing, this is because your
+installation failed the first time before the Zulip virtualenv was
+created. You can fix this by just closing the shell and running
+`vagrant ssh` again, or using `source .venv/bin/activate`.
+
+Finally, if you encounter any issues that weren't caused by your
+Internet connection, please report them! We try hard to keep Zulip
+development environment provisioning free of bugs.
+
+##### `pip install` fails during `vagrant up` on Linux
+
path: docs/development/setup/shared-vagrant-errors.md
user: login: laurynmm
body: Yes, that update makes sense. I didn't change that in my revisions.
created_at: 2025-05-20T13:58:29Z
author_association: COLLABORATOR

PR comments:
user: login: timabbott
created_at: 2024-12-16T20:39:13Z
body: This doesn't belong here. https://zulip.readthedocs.io/en/latest/development/setup-recommended.html#troubleshooting-and-common-errors is where we'd want a section like this, but unfortunately that doesn't have tabs yet. 

So I think if you want to pursue this, the first step would be to **carefully** rework the existing troubleshooting section to have separate sections for each installation type (E.g., the macOS-specific items only in that tab). Probably that should be its own prep PR.
author_association: MEMBER
user: login: apoorvapendse
created_at: 2024-12-17T00:59:14Z
body: 
> So I think if you want to pursue this, the first step would be to **carefully** rework the existing troubleshooting section to have separate sections for each installation type (E.g., the macOS-specific items only in that tab). Probably that should be its own prep PR.

Yes, I'll update that.
I am assuming the common sections have to be redundantly present in all tabs just like the prior parts.

author_association: COLLABORATOR
user: login: apoorvapendse
created_at: 2024-12-17T03:44:59Z
body: <details><summary>Image</summary>
<img src="https://github.com/user-attachments/assets/ec7d5b09-0484-4802-91e5-1c13f6658eaa"/>
</details>

<details><summary>Video</summary>

<video src="https://github.com/user-attachments/assets/1f1b28c2-f9e1-4c24-afe3-78a332899e2e"/>
</details>



@timabbott, I've added different tabs and also removed vbox related errors from unix based systems which use docker as the recommended provider in a different commit.
Does this match your expectations?
author_association: COLLABORATOR
user: login: apoorvapendse
created_at: 2025-01-09T06:41:49Z
body: Hello @timabbott,
Kindly TAL when you find the time.
I've written a [comment](https://github.com/zulip/zulip/pull/32719#issuecomment-2547443671) displaying & explaining the recent change
[source referred to before sending the reminder](https://zulip.readthedocs.io/en/8.4/contributing/contributing.html#:~:text=If%20you%20think%20the%20PR%20is%20ready%20and%20haven%E2%80%99t%20seen%20any%20updates%20for%20a%20couple%20of%20weeks%2C%20it%20can%20be%20helpful%20to%20leave%20another%20comment.%20Summarize%20the%20overall%20state%20of%20the%20review%20process%20and%20your%20work%2C%20and%20indicate%20that%20you%20are%20waiting%20for%20a%20review.).
author_association: COLLABORATOR
user: login: apoorvapendse
created_at: 2025-05-02T07:18:37Z
body: Some things I noticed:
1. We don't mention the VM setup for Windows using VirtualBox until [step 3](https://zulip.readthedocs.io/en/latest/development/setup-recommended.html#step-3-start-the-development-environment), which feels a bit confusing. One might install WSL and related dependencies only to find at step 3 that setup using VirtualBox was also an option, which is something they (maybe) would have preferred over WSL. Should we do something about this?

2. I assume using VirtualBox as the provider is possible for any platform. So would it be better to name the tabs as "VirtualBox" or "Vagrant(VirtualBox)" instead of calling them "Windows(VM)"?

3. We redundantly mention these four points of information and the preceding sentences in this section present before [Requirements](https://zulip.readthedocs.io/en/latest/development/setup-recommended.html#requirements)
![image](https://github.com/user-attachments/assets/e34c0c1d-8908-460c-ad16-c75023774217)

at the start of the [troubleshooting section](https://zulip.readthedocs.io/en/latest/development/setup-recommended.html#troubleshooting-and-common-errors) too. 
![image](https://github.com/user-attachments/assets/45a07575-79ac-4884-bc36-ffe7f5ead660)

Is that necessary?
author_association: COLLABORATOR
user: login: timabbott
created_at: 2025-05-08T17:54:46Z
body: I think WSL2 is going to be better for Windows for almost everyone and it's OK to not mention it early.

Agreed we can deduplicate the bug reporting details. I think that's likely a consequence of a past merge of different pages; WSL2 used to be on a different page entirely.
author_association: MEMBER
user: login: apoorvapendse
created_at: 2025-05-12T13:51:08Z
body: Thanks for the review @laurynmm.
I've largely followed your [recommendations](https://github.com/zulip/zulip/pull/32719/#pullrequestreview-2828789298) on structuring the commits, although I've renamed some files to improve clarity compared to the previous version.

Based on the flow of the documentation, the main [assumption](https://github.com/zulip/zulip/pull/32719/#discussion_r2083394279) I've made is that VirtualBox is used *only* for Windows as the host, which is why the current state has vbox related troubleshooting errors only in the Windows(VM) section.

Also posted [this](https://github.com/zulip/zulip/pull/32719/#discussion_r2083394067) question to discuss the scope for the `pip install` error.


author_association: COLLABORATOR
user: login: laurynmm
created_at: 2025-05-20T13:56:26Z
body: @apoorvapendse - Thanks for making those updates! I pushed a few more updates that make it easier to see when a commit in this series is changing the content of this documentation or when a commit is moving content of this documentation. I also revised some of the changes to the shared introduction to the troubleshooting errors section.

Let me know if you have any questions about my updates! Marking for integration review, but see note below.

@timabbott - I've reviewed all but the final commit of this series, so those are good for integration review. The final commit adds troubleshooting documentation for WSL, which I don't have any experience using, so I'm not sure if it makes sense for someone else to review the changes in that commit.
author_association: COLLABORATOR
user: login: zulipbot
created_at: 2025-05-20T16:35:55Z
body: Hello @zulip/server-development members, this pull request was labeled with the "area: documentation (developer)" label, so you may want to check it out!

<!-- areaLabelAddition -->

author_association: MEMBER
user: login: apoorvapendse
created_at: 2025-05-20T16:57:41Z
body: >Let me know if you have any questions about my updates! 

Thanks for the review and the updates, @laurynmm!
They make sense to me.


author_association: COLLABORATOR
user: login: timabbott
created_at: 2025-05-20T17:53:31Z
body: This seems great, thanks @apoorvapendse and @laurynmm for all the work on this! 
author_association: MEMBER