Official umbrelOS Troubleshooting Guide and FAQ

Guides
1

Overview

This guide provides troubleshooting steps and answers to frequently asked questions for umbrelOS (updated as of umbrelOS 1.2.1)

Encountering an issue with your umbrelOS server? We’ve put together a list of troubleshooting steps to help you resolve common problems.

Step 1: Take a look through the guide below to see if you can find a solution to your issue.

Step 2: If you cannot find a solution in this guide, search this forum and the official Umbrel Community Discord using keywords related to your problem. There’s a good chance someone has faced a similar issue and found a solution that could help you.

Step 3. If you’ve tried the steps above and still haven’t found a solution to your issue, create a post on this forum or the official Umbrel Community Discord describing your issue. There’s an entire community backing you!

If you feel overwhelmed or need further assistance, please connect directly with our official support team using the chat icon :speech_balloon: located at the bottom right of umbrel.com.

umbrelOS

umbrelOS is built specifically for Umbrel Home. Support for other devices is best-effort and not guaranteed. Compatibility issues may arise due to the differences in hardware, drivers, and other factors. Additionally, some issues may be related to your specific network configuration or the condition of your device’s hardware and accessories, and require more advanced troubleshooting steps that may not be directly related to umbrelOS.

At this stage in umbrelOS development, most issues can be resolved through the user interface at http://umbrel.local. However, rare issues may require more advanced troubleshooting steps. For most issues we recommend starting with the steps outlined under Simple solutions that work 99% of the time before attempting more advanced troubleshooting methods.

Simple solutions that work 99% of the time

  • “Have you tried turning it on and off again?”:
    Sometimes, the simplest solution is the best. If you’re experiencing any issue with your umbrelOS device, try restarting it before trying anything more complicated.

    umbrelOS should be restarted from the Settings page in your browser. Unplugging your umbrelOS device from the power source as a way of turning it off and on should only be done as a last resort, as it might cause data corruption and lead to more serious issues.

  • Check Hardware Quality and Compatibility:
    Hardware quality can often be the root cause of issues. Inspect your USB cables, hard drive, power adapter, and other components to ensure they are not damaged, and that they are properly connected. After replacing or reconnecting any components, restart your umbrelOS device from the Settings page in your browser.

  • Raspberry Pi Reliability Tips:
    The Raspberry Pi can be prone to various issues when used as a home server. The most common issues are related to the power supply and microSD card quality.

    Power Supply:
    It is crucial to use the official Raspberry Pi power supply. Third-party power supplies often cannot deliver the required current or maintain a stable voltage, leading to system instability, microSD card corruption, and corruption or data loss on connected hard drives.

    microSD card:
    Use a high-quality microSD card to avoid issues related to data corruption. Inferior cards can degrade over time, leading to read/write errors and system instability. If you suspect a microSD card issue, the first step is to re-flash the card with the latest version of umbrelOS. This will not result in any data loss, as all user data is stored on your external drive (SSD or HDD). To re-flash your microSD card, follow the steps on our website to “Install on a Raspberry Pi”. If this does not resolve the issue, you may need to replace the microSD card with a new one.

    If you are experiencing issues with your Raspberry Pi, and you replace the power supply with an official one, you should also re-flash or replace the microSD card. Power supply issues can cause corruption on the microSD card, and replacing the power supply without addressing potential microSD card corruption may not resolve the problem.

Installing umbrelOS on Raspberry Pi

umbrelOS is compatible with the Raspberry Pi 4 and 5. Earlier models are not supported. We recommend the Raspberry Pi 5 over the Raspberry Pi 4 for better performance and future-proofing. We also recommend the 8GB model of the Raspberry Pi 5, especially if you plan to run multiple apps on your umbrelOS device.

Steps to install umbrelOS on a Raspberry Pi are found on our GitHub wiki here “Install umbrelOS on a Raspberry Pi”. Please make sure to use the official Raspberry Pi power supply and a high-quality microSD card to avoid issues related to power supply and data corruption.

Seeing the account creation screen after restart/update on Raspberry Pi

If you see a new account creation screen after restarting or updating your Raspberry Pi device that you have previously set up, this is likely due to the Pi not mounting your external hard drive correctly. umbrelOS has not wiped your data, but an underlying issue with your Raspberry Pi or external storage device is preventing umbrelOS from accessing your data. The reason you see the new account creation screen is because umbrelOS falls back to using the microSD card as a storage device when it doesn’t detect an existing installation on the external hard drive.

To confirm this is the case, you can follow these steps:

  1. Access the umbrelOS terminal for your Raspberry Pi:
  • If you already created another account (not recommended), you can simply access the terminal through the web UI by going to Settings > Advanced Settings > Terminal > umbrelOS.
  • If you haven’t created another account (recommended), you can SSH into your Raspberry Pi by following the steps under “SSH access outside of web UI (advanced)” lower down in this guide.
  1. Run the lsblk command:

  • Once you have access to the terminal, type the following command into the terminal and press Enter:

    lsblk

  • This command will list all block devices on your Raspberry Pi. If your external hard drive is not listed, it means that your Raspberry Pi is not detecting the external hard drive.

    This is an example of what the output of the lsblk command might look like when your external hard drive IS detected. Note that the external hard drive is listed as sda and the microSD card is listed as mmcblk0. If you do not see the external hard drive listed, it means that the Raspberry Pi is not detecting the external hard drive.

    $ lsblk
NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
sda           8:0    0 931.5G  0 disk
`-sda1        8:1    0 931.5G  0 part /mnt/root/swap
                                    /swap
                                    /mnt/root/var/lib/docker
                                    /data/umbrel-os/var/lib/docker
                                    /var/lib/docker
                                    /data/umbrel-os/home/umbrel/umbrel
                                    /home/umbrel/umbrel
                                    /mnt/root/mnt/data
                                    /mnt/data
mmcblk0     179:0    0  29.7G  0 disk
|-mmcblk0p1 179:1    0   256M  0 part /run/rugpi/mounts/config
|-mmcblk0p2 179:2    0   128M  0 part /boot
|-mmcblk0p3 179:3    0   128M  0 part
|-mmcblk0p4 179:4    0     1K  0 part
|-mmcblk0p5 179:5    0     5G  0 part /run/rugpi/mounts/system
|-mmcblk0p6 179:6    0     5G  0 part
`-mmcblk0p7 179:7    0  19.2G  0 part /mnt/root/var/log
                                    /var/log
                                    /mnt/root/var/lib/systemd/timesync
                                    /var/lib/systemd/timesync
                                    /mnt/root/var/lib/docker
                                    /var/lib/docker
                                    /home
                                    /data
                                    /run/rugpi/state
                                    /run/rugpi/mounts/data

    Here is an example of what the output of the lsblk command might look like when your external hard drive is NOT detected. Note that ONLY the microSD card is listed as mmcblk0:

Troubleshooting steps:
The most common causes of this are power supply issues or data corruption on the external hard drive. The steps to troubleshoot this issue are to first check the power supply and then check the external hard drive for failure or data corruption.

  1. Power Supply:
  • Ensure you are using the official Raspberry Pi power supply. Third-party power supplies often cannot deliver the required current or maintain a stable voltage, leading to system instability, microSD card corruption, and corruption or data loss on connected hard drives.
  • If you suspect a power supply issue, replace the power supply with an official one, re-flash the microSD card with the latest version of umbrelOS to clear the extra user account (if you set one up) and ensure the microSD card is not corrupted, then restart your Raspberry Pi.
  1. External Hard Drive:
  • If you still encounter the same issue after replacing the power supply, the problem may be related to external hard drive failure or data corruption. This can be a direct result of power supply issues, but it can also be due to other factors like age, wear and tear, or other hardware issues.
  • If you have a spare external hard drive, try connecting it to your Raspberry Pi, restarting the device, and seeing if it is detected by running the lsblk command again. If the new external hard drive is detected, then the issue is likely with the original external hard drive.
  • If you suspect data corruption on the external hard drive you can connect it to a linux machine and see if it is recognized. You can also attempt to use disk repair tools to fix the issue. However, this can be complex and may result in data loss. If you are not comfortable with this process, we recommend seeking additional help.
  • If the above steps do not resolve the issue, the hard drive may be failing. Replace it with a new one and restore your data from a backup if available.
Installing umbrelOS on a custom x86 device

Steps to install umbrelOS on a custom x86 device are found on our GitHub wiki here “Install umbrelOS on x86 systems”.

Please note that umbrelOS is built specifically for Umbrel Home. Support for other devices is best-effort and not guaranteed. Compatibility issues may arise due to the differences in hardware, drivers, and other factors.

Understanding terminal output on custom x86 devices with connected displays

If you are installing umbrelOS on a laptop or have connected a monitor to your custom x86 device, you may see a terminal screen output when the device is powered on. This is normal and does not require any action on your part. The login prompt you see displayed in the terminal is for accessing the underlying operating system, and is not needed for the normal operation of umbrelOS. umbrelOS is designed to be accessed through a browser at http://umbrel.local once your device has booted up.

Terminal access is not recommended for most users, as it can lead to unintended changes that may disrupt your umbrelOS device. If you need to access the terminal for advanced troubleshooting, you can do so through the web UI by navigating to Settings > Advanced Settings > Terminal > umbrelOS.

That being said, here is an explanation of the login credentials:

Before you have created an account through the web UI, the login credentials for the terminal are:

  • Username: umbrel
  • Password: umbrel

Once you have created an account through the webUI, the login credentials for the terminal are:

  • Username: umbrel
  • Password: your account password you set during account creation
Installing umbrelOS on a Linux VM

Steps to install umbrelOS on a Linux VM are found on our GitHub wiki here “Install umbrelOS on a Linux VM”.

Please note that umbrelOS is built specifically for Umbrel Home. Support for other devices is best-effort and not guaranteed. Compatibility issues may arise due to the differences in hardware, drivers, and other factors.

How to update from umbrelOS 0.5 to 1.x

This is only for users who have installed umbrelOS 0.5 and want to update to umbrelOS 1.x. If you are installing umbrelOS 1.x fresh, you do not need to follow these steps.

umbrelOS 1.0 brings a complete architectural overhaul, and it’s been rebuilt as a standalone operating system that installs directly onto your device’s internal storage.

Umbrel Home users: Updating to umbrelOS 1.x can be done through the UI. Simply navigate to umbrel.local > Settings > “Check for update”, and click ‘Install Now’.

Raspberry Pi 4 users: Follow the steps here by clicking the “How to update” button: “Update Raspberry Pi 4 to umbrelOS 1.0”

Custom Linux users: Follow the detailed steps here: “How to update from umbrelOS 0.5 to umbrelOS 1.1 on Linux devices”

Linux VM users: Follow the steps here: “How to update from umbrelOS 0.5 on a Linux VM”

Migrating your Raspberry Pi data to Umbrel Home

Transferring all your existing data and apps from a Raspberry Pi umbrelOS server to Umbrel Home is a seamless, one-click process. Follow this guide for the step-by-step instructions: “How to migrate from a Raspberry Pi Umbrel to Umbrel Home”.

Note: Migrating to/from other devices is not yet officially supported.

Cannot access http://umbrel.local

After setting up your umbrelOS device and waiting a few minutes for it to boot up and become accessible, you should be able to access it by typing http://umbrel.local into your browser’s address bar. If you are unable to access http://umbrel.local, try the following steps:

  • Use the correct URL: Make sure you are typing http://umbrel.local exactly into your browser’s address bar. Do not use https://umbrel.local.

    If you are using Windows, try accessing http://umbrel without the .local suffix. Windows sometimes cannot resolve .local domains.

  • Check your network connection: Make sure the Ethernet cable is securely connected to both your device and your router, and that your umbrelOS device is connected to the same network as the device you are using to access it (e.g., your computer, smartphone, or tablet).

  • Disable VPNs: If you are using a VPN, try disabling it and accessing http://umbrel.local.

  • Try accessing it from a different browser: If you are unable to access http://umbrel.local on your current browser, try accessing it from a different browser to rule out browser-specific issues.

  • Try accessing it on another device: If you are unable to access http://umbrel.local on your current device, try accessing it on another device connected to the same network to rule out device-specific issues.

  • Check your router for connected devices: Make sure your umbrelOS device is connected to your network by checking your router’s list of connected devices.

    You can do this from your router’s app if it has one, or by logging into your router’s web interface (typically done by enterring an address like 192.168.1.1 into your browser’s address bar).

    Check the list of connected devices for “umbrel” and note down its IP address. Alternatively, use an app like Angry IP Scanner to scan your local devices and find your Umbrel server’s IP address.

    Once you have the IP address of your umbrelOS device, try accessing it by typing the IP address directly into your browser.

  • Running multiple umbrelOS devices?: If you are running more that one umbrelOS device, they will be available at umbrel.local, umbrel-2.local, etc. It is possible that on restarting your device, the hostname name may change due to network conditions. If you are unable to access http://umbrel.local, try accessing http://umbrel-2.local or http://umbrel-3.local, etc.

Where can I find my device's local IP address

Your device’s local IP address is assigned by your router and is used to identify your device on your local network. This IP address is displayed in the Settings page of your umbrelOS device.

If you are unable to access your device through http://umbrel.local to find your device’s local IP address, please follow the relevant troubleshooting steps in the “Cannot access http://umbrel.local” section above.

Setting a static IP address for your umbrelOS device

Setting a static IP address for your umbrelOS device is not currently supported through the web UI.

If you need to set a static IP address, you can do so through your router’s settings. Each router is different, so please refer to your router’s user manual or the manufacturer’s website for instructions on how to set a static IP address for a device on your network.

The general steps to set a static IP address for your umbrelOS device are as follows:

  • Access Your Router’s Settings: Open your router’s app (if available) or log into your router’s web interface through your browser. The web interface is typically accessed by entering an address like 192.168.1.1 into your browser’s address bar.

  • Navigate to the DHCP or LAN Settings: Find the section of your router’s settings that allows you to assign a static IP address to a device on your network. This is usually found under something like LAN, DHCP, or Reservations, but could be named differently depending on your router’s manufacturer and settings. This is where you can manage IP addresses for devices on your network.

  • Assign a Static IP Address: Locate your umbrelOS device in the list of connected devices and assign it a static IP address. Make sure to choose an IP address that is not already in use on your network.

  • Save Your Changes: Save the changes and reboot your router if necessary. Your umbrelOS device should now be assigned the static IP address you specified.

Connecting umbrelOS to Wi-Fi

As of umbrelOS 1.2, you can now connect your device to Wi-Fi after the initial account setup.

To connect your umbrelOS device to Wi-Fi, navigate to Settings > Wi-Fi and choose your network. Your device stays connected to your chosen Wi-Fi, even if the Ethernet cable is removed, and automatically reconnects to Wi-Fi on startup.

Disabling Wi-Fi may disconnect you from your Umbrel. To reconnect, plug in an Ethernet cable to your Umbrel and ensure that both your Umbrel and the device you’re accessing it from are on the same network.

Troubleshooting logs

You can generate troubleshooting logs through the umbrelOS web UI. These logs can help the community or the official support team diagnose issues and help you.

Navigate to Settings > Troubleshoot. Here you will find options for umbrelOS logs (operating system logs) and logs for specific apps running on your device. Select the log you want to view, and click the “Download” button to download the log file to your device.

If you are technical and comfortable with reading logs, you can review the logs yourself to identify potential issues. If you are unsure about the logs or need help interpreting them, you can share them with the community or the official support team for assistance.

SSH access outside of web UI (advanced)

Note: This section is for advanced users who require SSH access to their umbrelOS device outside of the web UI. SSH access is not recommended for most users, as it can lead to unintended changes that may disrupt your umbrelOS device. A terminal is also available in the web UI under Settings > Advanced settings > Terminal.

For advanced users who require SSH access to their umbrelOS device outside of the web UI, please follow these steps:

  1. Open a terminal window on your computer. For example, on macOS you can open the Terminal app that’s installed by default on every Mac, or on Windows you can open Command Prompt or the PowerShell app. If you are running umbrelOS on a custom x86 device with a connected display, you can also access the terminal through the display (skip to step 3 and use umbrel as the username).

  2. Type in the following command* and press the Enter key:

    ssh umbrel@umbrel.local

    *In the command given above, you can replace umbrel.local with the local IP of your Umbrel if you prefer. If you are using PowerShell on Windows 10, you may need to run ssh umbrel@umbrel instead of the command given above.

  3. You will then be prompted to enter your password. This is the same password you use to access umbrelOS through a browser. The default password before you have created an account through the web UI is umbrel. You will not be able to see your password as you type it into the terminal. Once you have typed in your password, press the Enter key.

    This will established an SSH connection to your umbrelOS server.

Resolving SSH warning - remote host identification has changed
If you are met with a warning message that “remote host identification has changed” when attempting to SSH into your umbrelOS device, this is likely due to the SSH key fingerprint changing due to a re-flash of umbrelOS on your device. To resolve this issue, you need to remove the old SSH key from your known_hosts file. Here’s how you can do that:

On the device you are trying to SSH from, find your known_hosts file.

  • on macOS and Linux, this file is usually located at ~/.ssh/known_hosts
  • on Windows, this file is usually located at C:\Users\your-username\.ssh\known_hosts

Open the known_hosts file in a text editor and delete all lines that corresponds to your umbrelOS device’s IP address or hostname. Save the file and try to SSH into your umbrelOS device again.

Why is umbrelOS now a standalone operating system?

umbrelOS 1.0 brings a complete architectural overhaul, and it’s been rebuilt as a standalone operating system that installs directly onto your device’s internal storage. This change is crucial because umbrelOS now handles low-level operations like disk partitioning and file-system management. And by operating in a fully controlled environment, it increases the security, performance, and stability of the entire system.

umbrelOS 1.0 implements a robust A/B partitioning scheme that enables OTA updates with rollback capabilities, allowing us to update the entire OS image, including drivers and the Linux kernel. This ensures we can deliver critical security updates reliably and safely — a limitation we faced previously when umbrelOS was layered on top of a user’s underlying Ubuntu/Debian operating system using a series of scripts and system services.

Note that as a result of the new OTA update architecture, any modifications made to the umbrelOS system (host OS) manually via ssh/terminal will not be saved across software updates. If you’re looking to run custom software in a Linux environment, consider using the Portainer app available in the Umbrel App Store.

When is feature X coming to umbrelOS?

Now that umbrelOS 1.0 has been released, our top priority is bringing heavily requested features like backups, https support, custom domains, and external storage to the platform. These features are not officially supported yet, but they are coming soon.

If you’d like to request a feature, please create a post in this forum, or the official Umbrel Community Discord, or our GitHub with your suggestion.

Apps

umbrelOS is a standalone operating system that does not come pre-installed with any apps. Once you have set up your umbrelOS device, you can install apps from the official Umbrel App Store, accessible by clicking on the App Store icon from your umbrelOS homescreen.

General troubleshooting for apps

If you are experiencing issues with a specific app on your umbrelOS device, follow these general troubleshooting steps:

  1. Restart the App:
    Sometimes, simply restarting the app can resolve issues. Right-click on the app icon from your umbrelOS homescreen and select the “Restart” option from the context menu. Wait a minute for the app to fully restart and then try accessing it again.

  2. Obtain Troubleshooting Logs:
    If restarting the app does not resolve the issue, you can obtain troubleshooting logs to help diagnose the problem. Right-click on the app icon from your umbrelOS homescreen and select the “Troubleshoot” option from the context menu. Click the “Download” button to download the log file to your device.

    If you are technical and comfortable with reading logs, you can review the logs yourself to identify potential issues. If you are unsure about the logs or need help interpreting them, you can share them with the community, the app’s official support channel, or the official Umbrel support team for assistance.

  3. Deciding who to contact for help:
    It can be difficult to decide who to reach out to for help with a specific app. You can always reach out to our official support channel on our website and we will either help you directly or point you in the right direction for further assistance. However, here are some general guidelines to help you get help from the best source:

  • It is always a good idea to first search this forum and the official Umbrel Community Discord for similar issues. There may be a solution already available that you can try.

  • If the app is built, maintained, and updated by Umbrel, please reach out to our official support through our website.

  • If the app is built, maintained, and updated by the developers of the app, you can reach out to the app’s official support channel for help. A link to the app’s official support channel is included in the app’s description in the Umbrel App Store.

  • If the app was submitted to the app store by a community member and is not maintained and updated by the official app’s developers, you can either reach out to the app’s official support channel (link included in the app’s description in the Umbrel App Store) or the official Umbrel support team for help. Please keep in mind when reaching out to the app’s official support channel that they may not be able to provide support for issues related to the app running on umbrelOS if the issue is specific to the platform.

Stop/start/restart apps

To stop, start, or restart an app on your umbrelOS device, simply right-click on an app icon from your umbrelOS homescreen and select the desired action from the context menu.

Default app credentials (username and password)

Some apps on the Umbrel App Store come with default credentials when the app is installed. You will need these to access the app.

If you forget the default credentials for an app, you can find them easily in two places:

  1. By right-clicking on the app icon from your umbrelOS homescreen and selecting the “Show default credentials” option from the context menu.
  2. In the app’s page on the Umbrel App Store from your umbrelOS device.

Note that if you have changed the credentials for an app through in-app settings, you will need to use the new credentials to access the app and are then responsible for remembering them.

Execute commands in app containers (advanced)

For advanced users who need to execute commands in an app’s container, you can do so via the terminal in the web UI. Navigate to Settings > Advanced Settings > Terminal, and select the desired app. This will open a terminal window where you can run commands in the app’s container.

For example, if you have the Bitcoin Node app installed and need to run a bitcoin-cli command, you would select the Bitcoin Core app from the list of apps in the terminal window and then run the desired command.

e.g., bitcoin-cli getblockchaininfo

If this does not give you the granularity you need to access specific containers within a specific app, you can go to Settings > Advanced Settings > Terminal > umbrelOS and run the following command to access any container:

sudo docker exec -it <container_name> /bin/bash

To get a list of all running containers, run the following command:

sudo docker ps

Installing processes and apps that are not in the App Store

Any modifications made to the umbrelOS system (host OS) manually via ssh/terminal will not be saved across software updates. Instead there are two supported ways to run custom software in a Linux environment on umbrelOS:

  • Portainer: The Portainer app is available in the Umbrel App Store and allows you to run custom containers on your umbrelOS device. This is the recommended way to run custom software on umbrelOS, as it is fully integrated with the platform and will persist across software updates.

  • Community App Stores: Community members have created app stores that allow you to install additional software on your umbrelOS device. Details on how to create your own Community App Store can be found here Umbrel Community App Store

    To add a Community App Store to your umbrelOS device, simply navigate to App Store and click the three dots in the top right corner.

Requesting app updates and new apps

If you would like to request an app update or a new app to be added to the Umbrel App Store, you can do so by creating a GitHub issue here umbrel-apps issues. We are also always grateful for community contributions, so if you are able to create a pull request with the necessary changes for an app update or a new app, that would be greatly appreciated.

10 Likes