diff options
Diffstat (limited to 'packages/docs/content/en/troubleshooting.mdx')
| -rw-r--r-- | packages/docs/content/en/troubleshooting.mdx | 525 |
1 files changed, 0 insertions, 525 deletions
diff --git a/packages/docs/content/en/troubleshooting.mdx b/packages/docs/content/en/troubleshooting.mdx deleted file mode 100644 index 6d97819..0000000 --- a/packages/docs/content/en/troubleshooting.mdx +++ /dev/null @@ -1,525 +0,0 @@ ---- -title: Troubleshooting -description: Common issues and solutions for DropOut launcher ---- - -# Troubleshooting - -This guide covers common issues and their solutions. If you don't find your issue here, please [open an issue](https://github.com/HydroRoll-Team/DropOut/issues) on GitHub. - -## Installation Issues - -### Linux: Missing Dependencies - -**Issue:** Error about missing libraries during installation - -**Solution:** -```bash -# Ubuntu/Debian -sudo apt update -sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 - -# Fedora -sudo dnf install webkit2gtk4.1 gtk3 - -# Arch -sudo pacman -S webkit2gtk gtk3 -``` - -### macOS: "App is damaged" - -**Issue:** macOS says DropOut is damaged and can't be opened - -**Solution:** -1. Open Terminal -2. Run: `xattr -cr /Applications/DropOut.app` -3. Try opening again -4. Or: System Preferences → Security → Allow anyway - -### Windows: SmartScreen Warning - -**Issue:** Windows SmartScreen blocks the installer - -**Solution:** -1. Click "More info" -2. Click "Run anyway" -3. This is normal for new apps without extended validation certificates - -## Authentication Issues - -### Microsoft Login Fails - -**Issue:** Can't complete Microsoft login - -**Possible causes and solutions:** - -**1. Device code expired:** -- Codes expire after 15 minutes -- Start the login process again -- Complete authorization faster - -**2. Network issues:** -- Check internet connection -- Disable VPN temporarily -- Check firewall settings -- Try different network - -**3. Microsoft account issues:** -- Verify account owns Minecraft Java Edition -- Check at https://www.minecraft.net/profile -- Ensure account is not suspended - -**4. Browser problems:** -- Try different browser -- Clear browser cache -- Disable ad blockers -- Use incognito/private mode - -### Token Refresh Fails - -**Issue:** Token refresh fails, must re-login frequently - -**Solution:** -1. Log out completely -2. Delete `accounts.json` from app data directory -3. Log in again -4. If persists, check Microsoft account status - -### Offline Login Not Working - -**Issue:** Can't create offline account - -**Solution:** -- Username must be 3-16 characters -- Use only letters, numbers, underscore -- No special characters -- No spaces - -## Game Launch Issues - -### Java Not Found - -**Issue:** "No Java installation found" - -**Solutions:** - -**1. Auto-detect existing Java:** -- Settings → Java → Detect Installations -- If found, select it -- If not found, proceed to step 2 - -**2. Download Java via DropOut:** -- Settings → Java → Download Java -- Select appropriate version: - - Java 8 for Minecraft 1.12.2 and older - - Java 17 for Minecraft 1.18-1.20.4 - - Java 21 for Minecraft 1.20.5+ - -**3. Manual Java installation:** -- Download from [Adoptium](https://adoptium.net/) -- Install to system -- Restart DropOut -- Detect again - -### Wrong Java Version - -**Issue:** Game crashes with "Unsupported class file version" - -**Solution:** -Match Java version to Minecraft version: - -| Minecraft Version | Java Version | -|-------------------|--------------| -| 1.7.10 and older | Java 8 | -| 1.8 - 1.12.2 | Java 8 | -| 1.13 - 1.16.5 | Java 8 or 11 | -| 1.17 - 1.17.1 | Java 16 | -| 1.18 - 1.20.4 | Java 17 | -| 1.20.5+ | Java 21 | - -### OutOfMemoryError - -**Issue:** Game crashes with `java.lang.OutOfMemoryError` - -**Solutions:** - -**1. Increase memory allocation:** -- Settings → Memory -- Increase Maximum Memory: - - Vanilla: 4GB minimum - - Light mods: 6GB - - Heavy modpacks: 8-12GB -- Don't exceed 80% of system RAM - -**2. Use 64-bit Java:** -- Check current Java architecture -- Download 64-bit Java if needed -- 32-bit Java limited to ~2GB - -**3. Reduce render distance:** -- In-game Video Settings -- Lower render distance to 8-12 chunks - -**4. Optimize JVM arguments:** -```bash --Xms4G -Xmx8G -XX:+UseG1GC -XX:+UnlockExperimentalVMOptions -``` - -### Game Won't Start - -**Issue:** Game doesn't launch, no error message - -**Check:** - -**1. Log output:** -- Check game console in DropOut -- Look for error messages -- Common issues: - - Missing files - - Corrupted downloads - - Mod conflicts - -**2. Verify files:** -- Delete version folder -- Re-download version -- Try vanilla first before modded - -**3. Check permissions:** -- Ensure DropOut can write to game directory -- Check folder permissions -- On Linux: ensure the launcher directory is only accessible by your user, e.g. `chmod 700 ~/.local/share/com.dropout.launcher` - -## Download Issues - -### Downloads Fail - -**Issue:** Asset or library downloads fail - -**Solutions:** - -**1. Network issues:** -- Check internet connection -- Disable VPN -- Try different network -- Check firewall/antivirus - -**2. Resume downloads:** -- DropOut auto-resumes interrupted downloads -- Close and reopen DropOut -- Downloads should continue - -**3. Clear download cache:** -- Delete `.part` files in libraries/assets -- Restart download - -**4. Manually download:** -- Check logs for failing URL -- Download file manually -- Place in correct location - -### Slow Downloads - -**Issue:** Downloads are very slow - -**Solutions:** - -**1. Adjust thread count:** -- Settings → Downloads -- Try different thread counts: - - Too low: slow overall - - Too high: connection throttling - - Recommended: 5-10 threads - -**2. Network optimization:** -- Close bandwidth-heavy apps -- Use wired connection if possible -- Check for ISP throttling - -**3. Alternative CDN:** -- Mojang mirrors may be slow -- Try at different time of day - -## Mod Loader Issues - -### Fabric Installation Fails - -**Issue:** Can't install Fabric loader - -**Solutions:** - -**1. Check Minecraft version:** -- Fabric supports 1.14+ -- Older versions not supported -- Try newer Minecraft version - -**2. Network issues:** -- Check internet connection -- Fabric Meta API may be down -- Try again later - -**3. Manual installation:** -- Download Fabric from [fabricmc.net](https://fabricmc.net/) -- Use official installer -- Import profile to DropOut - -### Forge Installation Fails - -**Issue:** Forge installer fails or hangs - -**Solutions:** - -**1. Java version:** -- Ensure correct Java version -- Forge 1.17+ requires Java 16+ -- Older Forge may need Java 8 - -**2. Installer timeout:** -- Forge installer can be slow -- Wait up to 10 minutes -- Check logs for progress - -**3. Disk space:** -- Ensure sufficient free space -- Forge needs ~1GB temporarily -- Check `/tmp` on Linux - -**4. Manual installation:** -- Download Forge installer from [minecraftforge.net](https://files.minecraftforge.net/) -- Run installer manually -- Select install client -- Import profile - -### Mod Crashes - -**Issue:** Game crashes with mods installed - -**Solutions:** - -**1. Check compatibility:** -- Verify mod is for correct Minecraft version -- Check mod loader version requirements -- Read mod description for dependencies - -**2. Install dependencies:** -- Fabric mods often need Fabric API -- Some mods require libraries -- Check crash log for "missing" errors - -**3. Remove conflicting mods:** -- Disable mods one by one -- Identify problematic mod -- Check for known conflicts -- Update or replace mod - -**4. Update mods:** -- Use latest mod versions -- Check mod update notes -- Some updates fix crashes - -## Performance Issues - -### Low FPS - -**Issue:** Game runs slowly or stutters - -**Solutions:** - -**1. Allocate more memory:** -- Increase max memory to 6-8GB -- Don't over-allocate (causes GC pauses) - -**2. Install performance mods:** -- **Fabric**: Sodium, Lithium, Phosphor -- **Forge**: OptiFine, Magnesium, Rubidium - -**3. Optimize settings:** -- Lower render distance -- Disable fancy graphics -- Turn off particles -- Disable VSync if fps < 60 - -**4. Update graphics drivers:** -- Download latest from manufacturer -- NVIDIA: GeForce Experience -- AMD: Adrenalin -- Intel: Graphics Command Center - -**5. Close background apps:** -- Free up system resources -- Disable overlays (Discord, etc.) -- Check Task Manager for CPU/RAM hogs - -### Launcher Slow to Start - -**Issue:** DropOut takes long time to launch - -**Solutions:** - -**1. Check system resources:** -- Close unnecessary programs -- Ensure sufficient RAM available -- Check CPU usage - -**2. Antivirus interference:** -- Add DropOut to exceptions -- Temporarily disable to test -- Some AVs slow down significantly - -**3. Corrupted data:** -- Delete `cache` folder in app data -- Restart DropOut -- Will rebuild cache - -## UI Issues - -### Window Won't Open - -**Issue:** DropOut window doesn't appear - -**Solutions:** - -**1. Check if running:** -```bash -# Linux/macOS -ps aux | grep dropout - -# Windows -tasklist | findstr dropout -``` - -**2. Kill and restart:** -```bash -# Linux/macOS -pkill dropout - -# Windows -taskkill /F /IM dropout.exe -``` - -**3. Reset window position:** -- Delete window state config -- Restart DropOut - -### Graphics Glitches - -**Issue:** UI looks wrong or has visual artifacts - -**Solutions:** - -**1. Update graphics drivers:** -- Install latest drivers -- Restart system - -**2. Disable hardware acceleration:** -- Check if option exists in settings -- May reduce performance but fix glitches - -**3. Try different monitor:** -- Multi-monitor setups can cause issues -- Try on different display - -## File System Issues - -### Can't Access Game Directory - -**Issue:** Errors accessing game files - -**Solutions:** - -**1. Check permissions:** -```bash -# Linux (set secure owner-only permissions) -sudo chown -R "$USER":"$USER" ~/.local/share/com.dropout.launcher -chmod -R u+rwX,go-rwx ~/.local/share/com.dropout.launcher - -# macOS (set secure owner-only permissions) -sudo chown -R "$USER":"$USER" ~/Library/Application\ Support/com.dropout.launcher -chmod -R u+rwX,go-rwx ~/Library/Application\ Support/com.dropout.launcher -``` - -**2. Check disk space:** -- Ensure sufficient free space -- Minecraft needs 2-10GB depending on mods -- Clean up old versions - -**3. Antivirus blocking:** -- Add game directory to exceptions -- Some AVs block file access - -### Corrupted Files - -**Issue:** Files appear corrupted or invalid - -**Solutions:** - -**1. Verify checksums:** -- DropOut verifies SHA1/SHA256 -- Failed verification triggers re-download - -**2. Re-download:** -- Delete corrupted file -- Launch version again -- DropOut will re-download - -**3. Clear cache:** -- Delete version folder entirely -- Re-install from scratch - -## Getting More Help - -### Collect Debug Information - -When reporting issues, include: - -**1. System information:** -- OS and version -- DropOut version -- Java version - -**2. Logs:** -- Launcher logs from console -- Game logs if applicable -- Error messages (full text) - -**3. Steps to reproduce:** -- What you did -- What you expected -- What actually happened - -**4. Screenshots:** -- Error messages -- UI issues -- Settings screens - -### Report Issues - -1. Search [existing issues](https://github.com/HydroRoll-Team/DropOut/issues) -2. If not found, [create new issue](https://github.com/HydroRoll-Team/DropOut/issues/new) -3. Use issue template -4. Provide all requested information -5. Be patient and responsive - -### Community Support - -- **GitHub Discussions**: Ask questions -- **Discord**: Real-time help (if available) -- **Documentation**: Check all guides - -## Known Issues - -### Currently Being Worked On - -- Multi-account switching (in progress) -- Custom game directory selection (planned) -- Launcher auto-update (planned) - -### Workarounds Available - -**Issue**: Can't switch between accounts easily -**Workaround**: Log out and log in with different account - -**Issue**: No built-in mod manager -**Workaround**: Manually manage mods in instance folder - -**Issue**: Can't import from other launchers -**Workaround**: Manually copy instance files |