Skip to content

Commit c9c6980

Browse files
dhofheinzdhofheinz
authored
docs: add Windows troubleshooting to WINDOWS.md (#334)
1 parent f987e1e commit c9c6980

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎WINDOWS.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,155 @@ Surprisingly: most guides in fact recommend running everything in an Admin Power
2929
- Install NVM: Restart PowerShell (still as Admin) and run `choco install nvm -y`
3030
- Install Node: Restart PowerShell (still as Admin) and run `nvm install node`
3131
- Install Codebuff: Run `npm i -g codebuff`
32+
33+
---
34+
35+
## Common Windows Issues & Troubleshooting
36+
37+
Running into problems? Here are solutions to the most common Windows-specific issues.
38+
39+
### Issue: "Failed to determine latest version" on First Run
40+
41+
**Symptom**:
42+
```powershell
43+
PS C:\> codebuff
44+
❌ Failed to determine latest version
45+
Please check your internet connection and try again
46+
```
47+
48+
**Cause**:
49+
Codebuff checks GitHub for the latest release on first run. This fails when:
50+
- Corporate firewall blocks `github.com`
51+
- Proxy settings not configured
52+
- Network connectivity issues
53+
- VPN required for external access
54+
55+
**Solutions**:
56+
57+
1. **Verify GitHub access**:
58+
```powershell
59+
curl https://github.com/CodebuffAI/codebuff/releases.atom
60+
```
61+
If this fails, you have a network/firewall issue.
62+
63+
2. **Configure npm proxy** (if behind corporate proxy):
64+
```powershell
65+
npm config set proxy http://your-proxy-server:port
66+
npm config set https-proxy http://your-proxy-server:port
67+
```
68+
69+
3. **Disable VPN temporarily** or whitelist GitHub in your firewall
70+
71+
4. **Clear npm cache and reinstall**:
72+
```powershell
73+
npm cache clean --force
74+
npm uninstall -g codebuff
75+
npm install -g codebuff
76+
```
77+
78+
**Reference**: Issue [#294](https://github.com/CodebuffAI/codebuff/issues/294)
79+
80+
---
81+
82+
### Issue: Git Commands Fail on Windows
83+
84+
**Symptom**:
85+
Git operations (commit, rebase, complex commands) fail with syntax errors or unexpected behavior.
86+
87+
**Cause**:
88+
Codebuff uses Windows `cmd.exe` for command execution, which:
89+
- Does not support bash syntax (HEREDOC, process substitution)
90+
- Has limited quote escaping compared to bash
91+
- Cannot execute complex git commands that work in Git Bash
92+
93+
**Solutions**:
94+
95+
1. **Install Git for Windows** (if not already installed):
96+
- Download from https://git-scm.com/download/win
97+
- Ensures git commands are available in PATH
98+
99+
2. **Use Git Bash terminal** instead of PowerShell:
100+
- Git Bash provides better compatibility with bash-style commands
101+
- Launch Git Bash and run `codebuff` from there
102+
103+
3. **Or use WSL (Windows Subsystem for Linux)**:
104+
- Provides full Linux environment with native bash
105+
- Install: `wsl --install` in PowerShell (Admin)
106+
- Run codebuff inside WSL for best compatibility
107+
108+
**Note**: Even when running in Git Bash, Codebuff spawns commands using `cmd.exe`. Using WSL provides the most reliable experience for git operations.
109+
110+
**Reference**: Issue [#274](https://github.com/CodebuffAI/codebuff/issues/274)
111+
112+
---
113+
114+
### Issue: Login Browser Window Fails to Open
115+
116+
**Symptom**:
117+
```
118+
Press ENTER to open your browser and finish logging in...
119+
120+
Caught exception: Error: Executable not found in $PATH: "start"
121+
Error: Executable not found in $PATH: "start"
122+
TLCWeb > Unable to login. Please try again by typing "login" in the terminal.
123+
```
124+
125+
**Cause**:
126+
When running Codebuff in Git Bash (MINGW64), the `start` command is not available in PATH. The browser auto-open feature fails.
127+
128+
**Solutions**:
129+
130+
1. **Manually open the login URL** (easiest):
131+
- Codebuff displays the login URL after the error
132+
- Copy the full URL starting with `https://codebuff.com/login?auth_code=...`
133+
- Paste into your browser
134+
- Complete login in browser
135+
- Return to terminal - login will succeed
136+
137+
2. **Use native Windows terminals**:
138+
- PowerShell: `powershell`
139+
- Command Prompt: `cmd`
140+
- These have `start` command available
141+
142+
3. **Clear cache if login still fails** (per issue #299):
143+
```powershell
144+
npm cache clean --force
145+
npm uninstall -g codebuff
146+
npm install -g codebuff
147+
```
148+
149+
**Reference**: Issue [#299](https://github.com/CodebuffAI/codebuff/issues/299)
150+
151+
---
152+
153+
### Message: "Update available: error → [version]"
154+
155+
**What it means**:
156+
This is **not an error** - it's an informational message indicating:
157+
- Your local binary needs to be downloaded/updated
158+
- "error" is a placeholder version (not a real error state)
159+
- Codebuff will automatically download the correct version
160+
161+
**What to do**:
162+
- Wait for the download to complete: "Download complete! Starting Codebuff..."
163+
- If download fails, check your internet connection
164+
- If it persists, try the solutions in "Failed to determine latest version" above
165+
166+
**Reference**: Issue [#299](https://github.com/CodebuffAI/codebuff/issues/299)
167+
168+
---
169+
170+
### Still Having Issues?
171+
172+
If these solutions don't resolve your problem:
173+
174+
1. **Search existing issues**: https://github.com/CodebuffAI/codebuff/issues
175+
2. **Open a new issue**: https://github.com/CodebuffAI/codebuff/issues/new
176+
3. **Join Discord community**: https://codebuff.com/discord
177+
178+
When reporting issues, please include:
179+
- Windows version: `winver` command
180+
- PowerShell/Git Bash/CMD
181+
- Node version: `node --version`
182+
- Full error message
183+
- Steps to reproduce

0 commit comments

Comments
 (0)