Common Issues

This guide covers the most frequently encountered issues with HomeDock OS Desktop and their solutions.

Installation Issues

Administrator Privileges Required (Windows)

Symptoms:

• Dialog asking to “Restart as Administrator”
• Installation fails or gets stuck

Cause: Windows requires administrator privileges to install WSL2, Docker, and Python for the first time.

Solution:

1. Close HomeDock OS Desktop
2. Right-click on the HomeDock OS Desktop icon
3. Select “Run as administrator”
4. Allow the installation to proceed
5. After successful setup, you won’t need admin rights anymore

Xcode Command Line Tools Required (macOS)

Symptoms:

• Installation stops with Xcode tools requirement
• Error about missing development tools

Solution:

1. Open Terminal
2. Run: xcode-select --install
3. Follow the installation prompts
4. Restart HomeDock OS Desktop after installation completes

Runtime Issues

Port Conflicts

Symptoms:

• “Port 80 is already in use” error
• HomeDock OS fails to start

Solution: See our detailed Port Conflicts guide for comprehensive solutions.

HomeDock OS Doesn’t Start

Symptoms:

• Installation completes but HomeDock OS doesn’t launch
• Blank window or endless loading

Solutions:

1. Check if services are running:

   • Windows: WSL2 and Docker should be active
   • macOS: Colima should be running

2. Restart the underlying services:

   • Windows: Restart WSL2 in PowerShell: wsl --shutdown then restart
   • macOS: Restart Colima: colima restart

3. Check port availability (see Port Conflicts guide)

Windows Update Errors

Symptoms:

• “Update Error: Unable to update automatically”
• Download succeeds but installation fails

Cause: Windows requires code signing certificates for automatic updates.

Solution:

1. Click “Download Now” when prompted
2. Visit homedock.cloud/install
3. Download and install the latest version manually
4. Previous version is uninstalled automatically

macOS Update Issues

Symptoms:

• “Manual Update Required” due to macOS security
• Code signature errors

Solution:

1. Allow the download from our official website
2. Check System Preferences > Security & Privacy
3. Allow HomeDock OS Desktop if blocked
4. Try the update again

Performance Issues

Slow Startup

Symptoms:

• HomeDock OS Desktop takes long to start
• Services take time to initialize

Solutions:

1. Ensure adequate resources:
   • Minimum 4GB RAM available
   • At least 2 CPU cores free
2. Check disk space:
   • Ensure 4GB+ free disk space
3. Restart underlying services:
   • Windows: Restart WSL2 and Docker
   • macOS: Restart Colima/Lima

High Resource Usage

Symptoms:

• System becomes slow when HomeDock OS is running
• High CPU or memory usage

Solutions:

1. Adjust resource allocation:

   • Windows: Configure WSL2 memory limits in .wslconfig
   • macOS: Adjust Colima/Lima resources

2. Close unnecessary applications before running HomeDock OS

3. Monitor resource usage and adjust accordingly

Network Issues

Cannot Connect to HomeDock OS

Symptoms:

• Browser shows “This site can’t be reached”
• Connection timeouts

Solutions:

1. Check if HomeDock OS is running:

   • Look for the HomeDock OS process
   • Check logs for errors

2. Verify port configuration:

   • Default is http://localhost:80
   • Check homedock_server.conf for custom ports

3. Check firewall settings:

   • Windows: Allow HomeDock OS through Windows Firewall
   • macOS: Check System Preferences > Security & Privacy

Cloud Instance Connection Issues

Symptoms:

• Cannot connect to cloud instances
• “Connection failed” errors

Solutions:

1. Verify instance URL format:

   • Should be like hostname.node1.homedock.cloud
   • Don’t include http:// or https://

2. Check internet connection

3. Try both HTTP and HTTPS:

   • HomeDock OS Desktop will automatically detect the correct protocol

Log Files and Debugging

Finding Log Files

Windows:

%APPDATA%\cloud.homedock.app\homedock\hdos_desktop.log

macOS:

~/Library/Application Support/cloud.homedock.app/homedock/hdos_desktop.log

Reading Logs

Look for these key indicators:

• [ERR] - Error messages
• [WRN] - Warning messages
• [PRG] - Progress updates

Recovery Options

Reset HomeDock OS Desktop

If issues persist, you can reset the installation:

1. Close HomeDock OS Desktop
2. Delete the HomeDock OS data folder:
   • Windows: %APPDATA%\cloud.homedock.app\homedock
   • macOS: ~/Library/Application Support/cloud.homedock.app/homedock
3. Restart HomeDock OS Desktop
4. Go through setup again

⚠️ Warning: This will delete all HomeDock OS data and settings.

Clean Reinstall

For persistent issues:

1. Uninstall HomeDock OS Desktop
2. Delete data folders (see above)
3. Restart your computer
4. Download fresh installer from homedock.cloud/install
5. Install again

Platform-Specific Issues

Windows-Specific

WSL2 Issues:

• Ensure Windows 10 Pro/Enterprise or Windows 11
• Enable virtualization in BIOS
• Update Windows to latest version

Docker Issues:

• HomeDock OS Desktop replaces Docker Desktop
• Don’t install both simultaneously
• Known compatibility issues with OrbStack too

macOS-Specific

Apple Silicon vs Intel:

• Different virtualization technologies
• Different resource requirements
• Some features may vary

Lima/Colima Issues:

• Check Homebrew installation
• Verify virtualization framework support

Getting Additional Help

Before Contacting Support

1. Check this troubleshooting guide, especially the Port Conflicts section
2. Review log files for specific errors, if applicable
3. Try basic solutions (restart, check ports, etc.), if you haven’t already
4. Note your system information:
   • Operating system version, build number
   • HomeDock OS Desktop version. Don’t forget to include the version of HomeDock OS Desktop you are using
   • Hardware specifications, including CPU, RAM, and disk space

Support Channels

1. Right here!
2. Email Support: support@homedock.cloud
3. Discord Community: Join the discussion on our Discord server
   • HomeDock OS Discord Server
   • Use the #support-ticket channel for help and select your issue type
   • Open a ticket for detailed issues
4. GitHub Issues: For bugs and feature requests

Information to Include

When seeking help, please provide:

• Error messages (exact text)
• Log file excerpts (relevant parts)
• System information (OS, version, hardware)
• Steps to reproduce the issue
• Screenshots if applicable

Every computer is different, and systems that have previously used WSL2, Docker Desktop, OrbStack or similar tools may behave unexpectedly. Since we can’t replicate every possible environment, the best way you can help us improve HomeDock OS Desktop is by sending your logs when something doesn’t work as expected. If your issue isn’t listed here, please open a ticket on our Discord server or contact us by email, if you’ve managed to find a solution, please share it with us so we can update the app and this guide and help others in the future.

REMEMBER: We have big plans for it, but HomeDock OS Desktop it’s still in Beta phase, so expect errors and issues, we’re doing our best to take it out of Beta as soon as possible. Most issues have simple solutions. Don’t hesitate to reach out if you need help!