This guide helps you resolve common issues with HexOS installation, setup, and operation. Issues are organized by category for quick reference.
💡 Quick Help
Check our Common Issues section for frequently encountered problems:
Visit the HexOS Discord Community for additional support from other users.
If you're having trouble creating a bootable USB drive from the HexOS ISO:
-
Use a different imaging tool
- Try balenaEtcher (recommended)
- On Windows: Use Rufus in DD mode
- On macOS: Use built-in Disk Utility or
dd command
- On Linux: Use
dd command or GNOME Disks
-
Try a different USB drive
- Use a high-quality USB 3.0+ drive (minimum 8GB)
- Some older or damaged USB drives can cause imaging problems
- Avoid using cheap or no-name USB drives
-
Download the ISO again
- Sometimes download corruption can cause imaging issues
- Verify the ISO checksum if provided
Installation problems can happen for various reasons:
-
Hardware compatibility
- Check the system requirements
- Ensure your hardware is on the supported hardware list
- Disable any hardware features that might interfere (virtualization, secure boot)
-
Corrupted installation media
- Re-create your USB installation drive with a fresh ISO download
- Try a different USB port (preferably USB 2.0 for compatibility)
-
Memory issues
- Run a memory test (memtest86+) if the installer crashes
- Try installing with minimal RAM configuration
Network connectivity problems after installation:
-
Physical connection
- Ensure ethernet cable is properly connected and working
- Try a different ethernet cable
- Check that network port LEDs are active
-
Network equipment issues
- Try connecting to a different network port
- Restart your router/switch
- Check if other devices can get IP addresses
-
Network configuration
- Some networks require manual IP configuration instead of DHCP
- Check if your network uses static IP assignments
- Verify network subnet and DHCP range
If deck.hexos.com can't find your server:
-
Network discovery requirements
- Server and browsing device must be on the same local network
- Some corporate/guest networks block device discovery
-
Firewall settings
- Check that your router/firewall isn't blocking mDNS discovery
- Ensure ports 80, 443, and 5353 are not blocked
-
Server status
- Verify the server has finished booting (wait 2-3 minutes)
- Check server status lights/indicators
- Try refreshing the discovery page
If you can't claim your server on deck.hexos.com:
-
Network connectivity
- Ensure your server can reach the internet
- Test that deck.hexos.com is accessible from your network
- Check for corporate firewall restrictions
-
Account issues
- Verify you're logged into the correct HexOS account
- Ensure your account is verified and active
-
Server already claimed
- Check if the server might already be claimed by another account
- Contact support if you need to transfer ownership
Authentication problems with the HexOS management portal:
-
Password problems
- Use the "Forgot Password" feature to reset your credentials
- Ensure you're using the correct email address
- Check that Caps Lock isn't affecting password entry
-
Account verification
- Check your email for account verification messages
- Look in spam/junk folders for verification emails
-
Browser issues
- Try clearing your browser cache and cookies (detailed instructions)
- Try a different browser or incognito/private mode
- Disable browser extensions that might interfere
When you can't authenticate to your local server:
-
Credential verification
- Use the default credentials from the installation process
- Check the server console for the correct username/password
-
Input issues
- Verify Caps Lock isn't affecting your password entry
- Ensure your keyboard layout matches what you used during setup
- Try typing the password in a text editor first to verify
If your drives aren't showing up:
-
Physical connections
- Ensure all SATA/power cables are properly connected
- Try different SATA ports or cables
- Check that drives spin up during boot
-
Drive compatibility
- Verify drives are supported by your hardware
- Check for any drive-specific firmware requirements
-
Power supply
- Ensure adequate power supply capacity for all drives
- Check that all power connectors are secure
Problems creating storage pools:
-
Drive preparation
- Drives must be unpartitioned for ZFS pool creation
- Use the HexOS interface to wipe drives if needed
-
Insufficient drives
- Mirror pools require at least 2 drives
- RAIDZ1 requires at least 3 drives
- RAIDZ2 requires at least 4 drives
If a task is taking too long or appears stuck in the Activities panel, you can manually dismiss it by enabling Experimental Features and clicking the X icon next to the task.
If your issue isn't covered here:
⚠️ Important
Always backup important data before making system changes or troubleshooting storage issues.