Leon4gr45/builder

1# Troubleshooting Guide2 3---4 5## Installation & Setup6 7### Node Version Errors8 9**Symptoms**:10```11Error: The engine "node" is incompatible with this module12```13 14**Solution**:15```bash16# Check current version17node -v18 19# Should be 18.x or higher20# Install correct version21nvm install 1822nvm use 1823 24# Or with Homebrew (macOS)25brew install node@1826```27 28### npm install Failures29 30**Symptoms**:31```32npm ERR! code ERESOLVE33npm ERR! ERESOLVE unable to resolve dependency tree34```35 36**Solutions**:37```bash38# Clear cache39npm cache clean --force40 41# Delete node_modules and package-lock42rm -rf node_modules package-lock.json43 44# Reinstall45npm install46 47# If still failing, use legacy peer deps48npm install --legacy-peer-deps49```50 51### Build Errors52 53**Symptoms**:54```55Error: Cannot find module '@next/swc-darwin-arm64'56```57 58**Solutions**:59```bash60# Reinstall dependencies61rm -rf node_modules .next62npm install63 64# Run build65npm run build66 67# If specific platform binary missing68npm install --force69```70 71---72 73## API & Provider Issues74 75### Invalid API Key76 77**Symptoms**:78- "Invalid API key" error79- 401 Unauthorized80- Authentication failed81 82**Solutions**:831. **Verify key is correct**:84   - Copy key directly from provider85   - Check for extra spaces86   - Ensure no line breaks87 882. **Check key permissions**:89   - OpenAI: Key must have chat/completions access90   - Anthropic: Key must be active91   - OpenRouter: Check credits balance92 933. **Re-enter key**:94   - Settings → Select provider → Click **Disconnect** → Paste new key → Click **Connect**95 96### Rate Limiting97 98**Symptoms**:99- "Rate limit exceeded" error100- 429 Too Many Requests101- Slow responses102 103**Solutions**:1041. **Wait before retrying**:105   - Wait 1 minute before next request106   - AI will auto-retry with backoff107 1082. **Switch models**:109   - Use different model with separate limits110   - Or switch provider temporarily111 1123. **Upgrade plan**:113   - Check provider's pricing page114   - Higher tiers often have higher limits115 116### Model Not Found117 118**Symptoms**:119- "Model not found" error120- 404 Model does not exist121- "Invalid model" message122 123**Solutions**:1241. **Check model name**:125   - Exact spelling required126   - Case-sensitive for some providers127 1282. **Refresh model list**:129   - Settings → Provider → Click refresh icon130   - Select from updated list131 1323. **Check provider access**:133   - Some models require special access134   - OpenAI: o1 requires tier 3+135   - Anthropic: Check beta access136 137### Connection Timeouts138 139**Symptoms**:140- Request timeout141- No response from AI142- Connection error143 144**Solutions**:1451. **Check internet connection**:146   - Test with other websites147   - Disable VPN temporarily148 1492. **Try different provider**:150   - Issue may be provider-specific151   - Switch to backup provider152 1533. **Check provider status**:154   - Visit provider's status page155   - OpenAI: status.openai.com156   - Anthropic: status.anthropic.com157 158### CORS Errors (Local Providers)159 160**Symptoms**:161```162Access to fetch blocked by CORS policy163```164 165**Solutions**:1661. **Ollama**: Ensure CORS enabled167```bash168# Set environment variable169export OLLAMA_ORIGINS="*"170# Restart Ollama171```172 1732. **LM Studio**: Enable CORS in settings174   - Settings → Server → Enable CORS175 1763. **Use proxy mode**:177   - OSW Studio has proxy routes that bypass CORS178 179---180 181## Generation Issues182 183### AI Not Responding184 185**Symptoms**:186- "Thinking..." indicator stuck187- No response after several minutes188- Request seems to hang189 190**Solutions**:1911. **Check browser console** (F12):192   - Look for JavaScript errors193   - Check network tab for failed requests194 1952. **Refresh page**:196   - Reload browser tab197   - Projects and conversation persist198 1993. **Try shorter prompt**:200   - Very long prompts may timeout201   - Break into smaller requests202 2034. **Switch models**:204   - Some models may be overloaded205   - Try different provider206 207### Tool Call Failures208 209**Symptoms**:210- Red X marks on tool executions211- "File not found" errors212- "Invalid path" errors213 214**Solutions**:2151. **Check file paths**:216   - Paths must start with `/`217   - Case-sensitive218 2192. **Verify file exists**:220   - Check file explorer221   - AI may be referencing old/deleted file222 2233. **Retry**:224   - AI usually retries automatically225   - Or rephrase request226 227### Loop Detection Triggered228 229**Symptoms**:230```231Loop detected: Preventing repeated failed command232```233 234**Solutions**:2351. **Different approach**:236   - AI was repeating failing command237   - Rephrase your request238   - Provide more context239 2402. **Manual fix**:241   - Fix the issue manually242   - Then ask AI to continue243 2443. **Fresh start**:245   - Start new conversation246   - Describe problem differently247 248### Out of Memory249 250**Symptoms**:251- Browser tab crashes252- "Out of memory" error253- Slow/unresponsive UI254 255**Solutions**:2561. **Close other tabs**:257   - Free up browser memory258 2592. **Smaller project**:260   - Split large project into parts261   - Delete unused files262 2633. **Restart browser**:264   - Close and reopen browser265   - Clear cache if needed266 267---268 269## Browser Mode Issues270 271### IndexedDB Quota Exceeded272 273**Symptoms**:274```275QuotaExceededError: The quota has been exceeded276```277 278**Solutions**:2791. **Delete old projects**:280   - Export important projects first281   - Delete unused projects282 2832. **Clear browser data**:284   - Keep OSW Studio origin285   - Or export all (.osws) then reimport286 2873. **Check browser quota**:288```javascript289// In console (F12)290navigator.storage.estimate().then(estimate => {291  console.log(`Using ${estimate.usage} of ${estimate.quota} bytes`);292});293```294 295### Lost Data After Clearing Cookies296 297**Symptoms**:298- All projects gone299- After clearing browser data300 301**Prevention**:302- Regular .osws exports (backups)303- Don't clear IndexedDB for OSW Studio origin304 305**Recovery**:306- Import last .osws backup307- Or start fresh308 309### Slow Performance with Large Projects310 311**Symptoms**:312- Laggy editor313- Slow file operations314- Preview takes long to load315 316**Solutions**:3171. **Reduce project size**:318   - Delete unused files319   - Compress images320   - Remove old assets321 3222. **Split project**:323   - Break into multiple smaller projects324 3253. **Use Server Mode**:326   - Server Mode handles large projects better327 328---329 330## Editor Issues331 332### Monaco Not Loading333 334**Symptoms**:335- Blank editor area336- "Loading editor..." stuck337- No syntax highlighting338 339**Solutions**:3401. **Refresh page**:341   - Hard refresh (Cmd/Ctrl+Shift+R)342 3432. **Check browser console**:344   - Look for Monaco-related errors345   - Network issues loading CDN346 3473. **Disable extensions**:348   - Browser extensions may interfere349   - Try in incognito/private mode350 351### File Not Saving352 353**Symptoms**:354- Changes not persisting355- "Save failed" error356- File reverts after close357 358**Solutions**:3591. **Check VFS**:360   - File explorer should update361   - If not, VFS write failed362 3632. **Try manual save**:364   - Cmd/Ctrl+S365   - Check for error messages366 3673. **Check browser storage**:368   - May be quota issue (see above)369 370### Tab Issues371 372**Symptoms**:373- Can't close tabs374- Tabs not switching375- Wrong file showing376 377**Solutions**:3781. **Refresh page**:379   - Editor state resets380 3812. **Close all tabs**:382   - Right-click → Close All383   - Reopen files from explorer384 385---386 387## Preview Issues388 389### Preview Not Updating390 391**Symptoms**:392- Changes not reflected393- Old version showing394- Preview stuck395 396**Solutions**:3971. **Manual refresh**:398   - Click ↻ button in preview399 4002. **Hard refresh preview**:401   - Right-click preview → Inspect402   - In DevTools: Right-click refresh → Hard Reload403 4043. **Save file first**:405   - Cmd/Ctrl+S406   - Then preview updates407 408### Assets Not Loading409 410**Symptoms**:411- Images broken (missing icon)412- CSS not applied413- JavaScript not running414 415**Solutions**:4161. **Check file paths**:417   - Absolute paths from the project root work: `/images/logo.png`418   - Relative paths also work: `./images/logo.png`419   - Paths are case-sensitive420 4212. **Verify files exist**:422   - Check file explorer423   - Correct spelling/case424 4253. **Check browser console**:426   - F12 → Console tab427   - Look for 404 errors428 429### Handlebars Errors430 431**Symptoms**:432```433Error: Missing partial: header434```435or436```437Error: Parse error on line 5438```439 440**Auto-fix**: In Code Mode, the AI can run `build` to check for compilation errors and fix them. You can also ask the AI to run `build` if you see errors in the preview.441 442**Manual solutions** (if the AI doesn't catch it, or in Chat Mode):4431. **Check partial exists**:444   - `/templates/header.hbs` must exist445   - Correct path in `{{> header}}`446 4472. **Check syntax**:448   - Closing tags match opening449   - Valid Handlebars syntax450 4513. **Check front matter**:452   - YAML between `---` delimiters453   - Valid YAML syntax454 455### Blob URL Issues456 457**Symptoms**:458- `blob:http://localhost...` URLs459- Images work in preview but not export460 461**Solution**:462- This is normal for preview463- Export compiles to regular paths464- Deploy exported ZIP, not preview465 466---467 468## Export Issues469 470### ZIP Download Fails471 472**Symptoms**:473- Export button does nothing474- Download starts but fails475- Corrupted ZIP file476 477**Solutions**:4781. **Check browser permissions**:479   - Allow downloads for site480 4812. **Try different browser**:482   - Chrome, Firefox, or Safari483 4843. **Smaller project**:485   - If project very large, may timeout486   - Remove unused assets487 488### Missing Files in Export489 490**Symptoms**:491- Exported ZIP incomplete492- Some files missing493- Folder structure wrong494 495**Solutions**:4961. **Check file explorer**:497   - Ensure all files saved498   - Cmd/Ctrl+S499 5002. **Wait for export to complete**:501   - Large projects take time502   - Don't interrupt download503 5043. **Re-export**:505   - Try export again506   - Check ZIP contents507 508### Handlebars Not Compiled509 510**Symptoms**:511- `.hbs` files in ZIP512- `{{> partial}}` syntax in output513- Site broken when deployed514 515**Solution**:516- Ensure using "Export → ZIP" (not .osws)517- ZIP export auto-compiles Handlebars518- If issue persists, report bug519 520---521 522## Performance Issues523 524### Slow AI Responses525 526**Symptoms**:527- Long wait times528- "Thinking..." for minutes529 530**Causes**:531- Provider-side latency532- Model overload533- Large context534 535**Solutions**:5361. **Switch models**:537   - Try faster model (smaller size)538   - Or different provider539 5402. **Reduce context**:541   - Start fresh conversation542   - Delete old messages543 5443. **Use streaming**:545   - Most providers support streaming546   - See partial responses as they generate547 548### Slow File Operations549 550**Symptoms**:551- Laggy editor typing552- Slow file explorer553- Preview delays554 555**Solutions**:5561. **Reduce project size**:557   - Delete unused files558   - Optimize images559 5602. **Close unused tabs**:561   - Only open files you need562 5633. **Restart browser**:564   - Free up memory565 566### High Memory Usage567 568**Symptoms**:569- Browser tab uses lots of RAM570- Computer fan running571- Other apps slow572 573**Solutions**:5741. **Close other tabs/apps**:575   - Free system resources576 5772. **Smaller projects**:578   - Split into multiple projects579 5803. **Use Server Mode**:581   - Offload storage to server582 583---584 585## Still Having Issues?586 5871. **Check documentation**: Other guides may have answers5882. **Browser console**: F12 → Console for error details5893. **Report bug**: [GitHub Issues](https://github.com/o-stahl/osw-studio/issues)590 591**When reporting**:592- Describe expected vs actual behavior593- Include error messages594- Browser and OS version595- Steps to reproduce596