Skip to content

Commit 214b12c

Browse files
hanyunguobmcutler
andauthored
[Documentation:Developer] Add Troubleshooting Document (#594)
**Overview:** This pull request aims to improve the troubleshooting documentation related to setting up a MacBook Pro M3 with ARM64 architecture. After encountering a unique issue during my own setup process and confirming with the Submitty Zulip Community Discussion that this issue hasn't been encountered before, I decided to contribute to the project by documenting the steps to troubleshoot and resolve similar issues. **Changes Made:** Added a new section titled "SSH connection was unexpectedly closed" to the installation_troubleshooting.md file. **Purpose:** The purpose of this contribution is to: 1. Help future users who may encounter similar issues during their MacBook Pro M3 setup process. 2. Improve the overall user experience by providing comprehensive troubleshooting guidance. 3. Contribute back to the community by sharing knowledge and solutions for uncommon issues. **Testing:** I have tested the troubleshooting steps provided in the documentation on my MacBook Pro M3 (ARM64) setup to ensure accuracy and effectiveness. **Additional Notes:** Feedback and suggestions for further improvements are welcome. Co-authored-by: Barb Cutler <[email protected]>
1 parent 7297560 commit 214b12c

File tree

1 file changed

+82
-1
lines changed

1 file changed

+82
-1
lines changed

_docs/developer/troubleshooting/installation_troubleshooting.md

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,88 @@ broadcast 192.168.56.255
186186
187187
References and useful links: [https://gist.github.com/pjdietz/5768124](https://gist.github.com/pjdietz/5768124) and [http://christophermaier.name/2010/09/01/host-only-networking-with-virtualbox/](http://christophermaier.name/2010/09/01/host-only-networking-with-virtualbox/)
188188
189+
---
190+
191+
## SSH connection was unexpectedly closed
192+
193+
* If you see an error similar to on ARM64 Machine (Apple Silicon):
194+
195+
```
196+
The SSH connection was unexpectedly closed by the remote end. This
197+
usually indicates that SSH within the guest machine was unable to
198+
properly start up. Please boot the VM in GUI mode to check whether
199+
it is booting properly.
200+
```
201+
202+
This error message is indicating that there may be a problem with the SSH service on the VM, and you should check the VM's graphical interface to troubleshoot and ensure that it is starting up correctly.
203+
204+
205+
#### Try the following steps:
206+
207+
* Reinstalls Vagrant using Homebrew
208+
```
209+
brew reinstall --cask vagrant
210+
```
211+
212+
* Updates the Vagrant plugins to the latest versions
213+
```
214+
vagrant plugin update
215+
```
216+
217+
* Updates the Vagrant box to the latest version
218+
```
219+
vagrant box update
220+
```
221+
222+
* Verify qemu is install correctly
223+
224+
* Firstly, use this command will display the installed version of QEMU for ARM64.
225+
```
226+
qemu-system-aarch64 --version
227+
```
228+
229+
* Secondly, Verify that the QEMU binary for ARM64 is accessible in your system's PATH by running:
230+
```
231+
which qemu-system-aarch64
232+
```
233+
234+
*Note: This command will display the path to the QEMU ARM64 binary (e.g., /opt/homebrew/bin/qemu-system-aarch64)
235+
236+
* Verify Vagrant Installation
237+
```
238+
vagrant --version
239+
```
240+
241+
* Verify Path: if Vagrant is installed but the command is not recognized, it might be due to the PATH variable not including the directory where Vagrant is installed.
242+
```
243+
echo $PATH
244+
```
245+
246+
* If Vagrant's directory is not in your PATH, you can add it temporarily for the current session by running:
247+
248+
```
249+
export PATH="/path/to/vagrant/directory:$PATH"
250+
```
251+
* You should replace `/path/to/vagrant/directory` with the actual path where Vagrant is installed
252+
* You can find the path by runing command `which vagrant` or `where vagrant`
253+
* For example, if Vagrant is installed in `/usr/local/bin/vagrant`, the export command would look like this:`export PATH="/usr/local/bin:$PATH"`
254+
255+
* Removes the `.vagrant` folder, which stores Vagrant environment settings and state. This step effectively resets the Vagrant environment.
256+
```
257+
rm -r .vagrant
258+
```
259+
260+
* Destroys the Vagrant environment, shutting down and removing the associated VM instance
261+
```
262+
vagrant destroy
263+
```
264+
265+
* Boots up a new Vagrant environment using the QEMU provider
266+
```
267+
vagrant up --provider=qemu
268+
```
269+
270+
---
189271
190272
## Guest Additions
191273
@@ -216,4 +298,3 @@ Some things to check:
216298
rm -rf /Users/MY_HOME_DIRECTORY/.vagrant.d/
217299
rm -rf /Users/MY_HOME_DIRECTORY/.gem/specs/rubygems.org%443/quick/Marshal.4.8/vagrant-vbguest-0.31.0.gemspec
218300
```
219-

0 commit comments

Comments
 (0)