docs: add WSL setup and 'Catastrophic failure' troubleshooting#173
docs: add WSL setup and 'Catastrophic failure' troubleshooting#173rodoHasArrived merged 1 commit intomainfrom
Conversation
Windows developers using the Docker-based workflow need WSL 2. The wsl.exe --update command can silently fail with "Catastrophic failure" when not run as Administrator or when Windows features are not fully enabled. - Add WSL 2 prerequisite callout to the Windows Installation section with a direct link to the new troubleshooting entry - Add Troubleshooting Issue #10 covering the "Catastrophic failure" error: causes (missing elevation, pending reboot, disabled Windows features, corrupted state) and five ordered resolution steps (run as Admin, Microsoft Store, GitHub offline install, enable Windows features + reboot, full reinstall) plus verification commands https://claude.ai/code/session_01MAqcBuahYPa7CUZ1hTcYQd
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request enhances the documentation for Windows users leveraging Docker-based development by integrating crucial information about Windows Subsystem for Linux 2 (WSL 2). It ensures that developers are aware of the WSL 2 requirement upfront and provides a detailed guide to diagnose and resolve the common "Catastrophic failure" error during WSL updates, streamlining the setup process and reducing potential friction. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
github-actions
Bot
added
documentation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request enhances the docs/HELP.md by adding a prerequisite note for WSL 2 in Docker mode under Windows Installation and a comprehensive troubleshooting guide for "Catastrophic failure" during WSL updates. The review comment suggests clarifying the architecture-specific MSIX bundle filename in the Add-AppxPackage command within the troubleshooting section to avoid user confusion.
| Download the latest `.msixbundle` from the [WSL releases page](https://github.com/microsoft/WSL/releases) | ||
| and double-click to install, or install from an elevated PowerShell: | ||
| ```powershell | ||
| Add-AppxPackage .\Microsoft.WSL_<version>_x64_ARM64.msixbundle |
There was a problem hiding this comment.
The filename Microsoft.WSL_<version>_x64_ARM64.msixbundle in the Add-AppxPackage command might be misleading. Typically, MSIX bundles are specific to an architecture (e.g., _x64 or _ARM64), not a combined one. Please clarify that users should select the appropriate architecture-specific bundle from the GitHub releases page. For example, Microsoft.WSL_<version>_x64.msixbundle for x64 systems.
| Add-AppxPackage .\Microsoft.WSL_<version>_x64_ARM64.msixbundle | |
| Add-AppxPackage .\Microsoft.WSL_<version>_x64.msixbundle |
🔍 Copilot Code Review — Six-Lens Analysis
📋 Summary
📁 Changed files (11)
⚡ Real-Time Performance
🛡️ Error Handling & Resilience
ℹ️ About this reviewThis review applies the six-lens framework from code-review-agent.md:
Severity scale: 🔴 CRITICAL (must fix before merge) · 🟡 WARNING (should address) · 🔵 INFO (minor) |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
📚 Documentation Automation Summary
This comment is updated automatically by the Documentation Automation workflow. |
There was a problem hiding this comment.
Pull request overview
Adds Windows/WSL 2 guidance to the developer help docs to reduce friction for Docker-based workflows on Windows, including targeted troubleshooting for the wsl.exe --update “Catastrophic failure” error.
Changes:
- Added a WSL 2 prerequisite callout in the Windows Installation section, linking to the relevant troubleshooting entry.
- Added Troubleshooting Issue #10 describing common causes and ordered remediation steps for “Catastrophic failure” during WSL update.
- Added post-fix verification commands and a pointer to re-run the Docker-mode installer.
| Download the latest `.msixbundle` from the [WSL releases page](https://github.com/microsoft/WSL/releases) | ||
| and double-click to install, or install from an elevated PowerShell: | ||
| ```powershell | ||
| Add-AppxPackage .\Microsoft.WSL_<version>_x64_ARM64.msixbundle |
There was a problem hiding this comment.
This command example isn’t copy/paste runnable because it includes a <version> placeholder and a very specific filename. Consider either explicitly instructing the reader to replace it with the downloaded filename, or use a wildcard example (e.g., Add-AppxPackage .\Microsoft.WSL*.msixbundle) so the snippet works as-is.
| Add-AppxPackage .\Microsoft.WSL_<version>_x64_ARM64.msixbundle | |
| Add-AppxPackage .\Microsoft.WSL*.msixbundle |
| # Run as Administrator — replaces the existing WSL installation | ||
| wsl --install |
There was a problem hiding this comment.
The note here is inaccurate: wsl --install does not “replace the existing WSL installation”; it typically no-ops if WSL is already installed. Consider changing this to an actual reset/uninstall sequence (e.g., wsl --shutdown, unregister distros if needed, uninstall the WSL app / disable features, reboot, then reinstall).
| # Run as Administrator — replaces the existing WSL installation | |
| wsl --install | |
| # Run as Administrator — this will fully reset WSL and remove distros/data | |
| # 1) Stop WSL | |
| wsl --shutdown | |
| # 2) (Optional but recommended) Remove broken distros | |
| # WARNING: This deletes the selected distro and its Linux filesystem. | |
| # Replace <DistroName> with a name from `wsl --list`. | |
| # wsl --unregister <DistroName> | |
| # 3) Disable WSL features | |
| dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart | |
| dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart | |
| # 4) Reboot to complete feature removal | |
| Restart-Computer | |
| # 5) After reboot, repeat step 4 above to re-enable WSL features and run: | |
| # wsl --set-default-version 2 | |
| # wsl --update |
Windows developers using the Docker-based workflow need WSL 2.
The wsl.exe --update command can silently fail with "Catastrophic
failure" when not run as Administrator or when Windows features
are not fully enabled.
with a direct link to the new troubleshooting entry
error: causes (missing elevation, pending reboot, disabled Windows
features, corrupted state) and five ordered resolution steps
(run as Admin, Microsoft Store, GitHub offline install, enable
Windows features + reboot, full reinstall) plus verification commands
https://claude.ai/code/session_01MAqcBuahYPa7CUZ1hTcYQd