Back to Documentation

Troubleshooting

Solutions to common problems and issues you might encounter with OmniSet.

Run the Doctor Command

OmniSet includes a built-in diagnostic tool. Run it first to identify issues:

bash 
./bin/omniset doctor

Installation Fails

If the installation script fails to run:

  1. Check your internet connection - OmniSet needs to download packages
  2. Verify sudo access - Run sudo whoami to test
  3. Update package lists first:
bash 
sudo apt update && sudo apt upgrade -y

Module Not Found

If a module isn't recognized:

  1. Check the module name - Use ./bin/omniset list to see all available modules
  2. Check by category - Use ./bin/omniset list --category development
  3. Get module info - Use ./bin/omniset info <module-name>

Package Conflicts

If you see errors about broken or conflicting packages:

  1. Fix broken packages:
bash 
sudo apt --fix-broken install
sudo dpkg --configure -a
sudo apt autoremove

Docker Permission Denied

If you get permission errors running Docker:

  1. Add yourself to the docker group:
  2. Log out and back in (or reboot)
bash 
sudo usermod -aG docker $USER

Web Interface Won't Open

If the browser-based selector doesn't open:

  1. Check if a browser is installed - OmniSet needs a default browser
  2. Try the interactive CLI instead:
bash 
./bin/omniset install --interactive

Unsupported Distribution

If your distro isn't supported:

Supported: Ubuntu 20.04+, Debian 11+, Fedora, Arch, openSUSE, Alpine

For other distributions, you can try:

  1. Check if your distro is Debian-based - it might work
  2. Open an issue on GitHub requesting support
  3. Contribute support for your distro

Getting Help

If you can't solve your issue:

  1. Search existing issues on GitHub
  2. Open a new issue with:
    • Your distribution and version
    • The exact error message
    • Output from ./bin/omniset doctor
    • Steps to reproduce
  3. Join discussions for community help

Was this helpful?

Help us improve the documentation

Suggest an edit