Official Umbrel Troubleshooting Guide and FAQ

[mayank]

Overview

Facing an issue with your Umbrel server or any of the apps on it? Don’t worry, we’re here to help! We recommend trying the following steps, and if you still need help, feel free to reach out to us directly:

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 Umbrel’s Telegram community with 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 Umbrel’s Telegram community describing your issue. There’s an entire community backing you!

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

Umbrel - Troubleshooting & FAQ

Our aim is to simplify the user experience by making it as easy as possible to resolve issues directly from the app interface. However, at this stage in the product’s development you may need to access your Umbrel manually via SSH (Secure Shell) and perform more advanced troubleshooting steps to resolve your issue.

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 issues with Umbrel, try restarting it from the settings page before trying anything more complicated. Unplugging your Umbrel server 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.

• Hardware quality and compatibility can sometimes be the root cause of issues, particularly for Raspberry Pi setups. Inspect the condition of the USB cable, hard drive, fan, microSD card, power adapter, etc to see if they are damaged. We recommend using the hardware listed on umbrel.com, and to use the official Raspberry Pi power supply.

• If you’re running Umbrel on a Raspberry Pi, it is possible for the operating system on the microSD card to become corrupted due to power interruptions or other factors. Re-flashing the microSD card can often resolve the problem. This will not result in any data loss because all user data is stored on your external drive (SSD or HDD). To reflash your microSD card, follow the steps on our website to “Install on a Rasberry Pi 4”.

Raspberry Pi Compatibility

A Raspberry Pi 4 with at least 2GB of RAM is required to run Umbrel OS, but we recommend 8GB of RAM for optimal performance. Unfortunately, the Raspberry Pi 3 is not compatible with Umbrel OS as it only supports 32-bit operating systems, whereas Umbrel OS is a 64-bit operating system.

Installing Umbrel on Non-Raspberry Pi Hardware

You can install Umbrel on anything that runs Linux! Install Ubuntu or Debian on your chosen platform such as a single board computer, laptop, desktop, virtual machine, Proxmox, or cloud server. Once the operating system is in place, run the following command to install Umbrel:

curl -L https://umbrel.sh | bash

We recommend using a system with at least 2GB RAM.

Disk space requirements

The disk space you need ultimately depends upon your use-case. Umbrel, in itself, only requires about 1-2GB of space. The rest depends upon which apps you use. For example, if you plan to run a Bitcoin node on your Umbrel, it will consume around 500GB of space, so our recommendation would be to go with at least 1TB of free space. If you plan to use Nextcloud, PhotoPrism, and such for your media library, or Jellyfin/Plex to stream your content, again — the space you’d need would depend upon the size of your library, but as a safe bet and for enough future-proofing, 1TB+ is recommended.

How to SSH into Umbrel on a Rasberry Pi

SSH (Secure Shell) is a way to access and control a device, such as your Umbrel server running on a Raspberry Pi, via the command line. To access Umbrel via SSH, follow these steps:

1. Open a terminal window on your computer. On macOS, you can open the Terminal app that’s installed by default on every Mac. On Windows, you can open Command Prompt or the PowerShell app.

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

   ssh -t 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 your Umbrel through a browser. The default password before you have created an account on your Umbrel is moneyprintergobrrr. 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 Umbrel server. You can now begin using the command line interface to perform various actions and troubleshoot issues that require SSH.

Resolving Remote Host Error when attempting to SSH

If you receive an error that looks like this when attempting to SSH into your Umbrel:

@@@@@@@@@@@@@@@@@@@@@@@@ 
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @ 
@@@@@@@@@@@@@@@@@@@@@

You just need to delete the known_hosts file in this directory on your computer:

On Mac: ~/.ssh

On Windows: C:\users\<your-windows-username>\.ssh\

Troubleshooting on Linux

This guide uses commands that assume Umbrel is installed in the home directory of your Linux machine, which is denoted by the tilde symbol ~ . If you installed Umbrel in a different location than the default home directory, you must replace ~ with the actual path to the Umbrel folder in the commands provided in this guide.

For example, you would replace ~ in the command below with the path to your Umbrel installation directory:

`sudo ~/umbrel/scripts/debug`

Generating Troubleshooting Logs

You can generate troubleshooting logs from your Umbrel to help diagnose an issue with your device and any apps that you have installed.

To generate logs from the Umbrel web interface:

1. Access your Umbrel through a web browser
2. Go to “Settings”
3. Click “Start” next to “Troubleshooting” to generate the logs

If you are unable to access your Umbrel through a web browser, you can generate troubleshooting logs from the command line by following these steps:

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   sudo ~/umbrel/scripts/debug

To generate more detailed logs for a specific app, follow these steps:

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command (Lightning Node example). If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   ~/umbrel/scripts/app compose lightning logs --tail 250

   You can replace “lightning” with the name of the app you want to view the logs for. A list of app names can be found here: https://github.com/getumbrel/umbrel-apps. Simply use the name of the folder for the app you want to view the logs for.

To get help understanding the logs and any steps required to solve the issue, copy and paste your logs into https://0bin.net and then share that link here in the forum, Umbrel’s Telegram community, or with the Umbrel team using the chat icon located at the bottom right of Umbrel.com.

Raspberry Pi Boot Issues

If your Raspberry Pi will not boot up, disconnect any devices that are connected to the Raspberry Pi’s GPIO pins, such as a fan. Now try restarting the Raspberry Pi by unplugging and plugging it back in to the power source.

If this does not resolve your issue, please connect directly with the Umbrel team using the chat icon located at the bottom right of umbrel.com.

Issues Accessing your Umbrel via Web Browser

If you cannot access your Umbrel from a web browser, follow these steps to see if your router has detected the Umbrel server:

1. Log in to your router’s admin portal, typically done by entering an address like 192.168.1.1 into your web browser.
2. Check the list of connected devices for Umbrel.

Two common reasons that your Umbrel may not appear on the list are:

1. The Ethernet cable is not properly plugged in.
2. The Raspberry Pi is not booting up properly.

If checking the Ethernet cable and troubleshooting the boot issues outlined in Raspberry Pi Boot Issues do not resolve the issue, please connect directly with the Umbrel team using the chat icon located at the bottom right of umbrel.com.

Setting a Fixed IP Address for Umbrel on Raspberry Pi

Please follow this dedicated guide detailing how to assign a fixed IP address to your Umbrel.

Resetting Your Umbrel Password

Unfortunately, to maximize security and prevent unauthorized access, there is no way to reset your Umbrel password if you lose it. You will need to start fresh by reformatting your drive if you’re a Raspberry Pi user, or reinstalling Umbrel for Linux users. If you have critical app data that you cannot afford to lose, you can try to recover it from the app-data directory inside your Umbrel installation. For Raspberry Pi users, you can find this directory by connecting your external drive to any Linux system and going to umbrel/app-data .

Note: The above approach will not work for Lightning Node app data. Here’s a very simple and elegant way to restore your Lightning node on a fresh Umbrel installation:

1. Install the Lightning Node app
2. Select “Recover your previous node”
3. Enter your 24 secret words
4. Select an automatic encrypted backup of your channels or upload your own backup file, and that’s it. Here is a demo of the Automatic Channel Recovery tool.

Lost Two-Factor Authentication (2FA) Access

To disable Two-Factor Authentication (2FA) if you have lost access to your 2FA app but still remember your Umbrel password, follow these steps:

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   json_file="~/umbrel/db/user.json" && contents="$(jq 'del(.otpUri)' ${json_file})" && echo "${contents}" > ${json_file}

This will disable 2FA.

Issues Updating Umbrel via Web Browser

If you are unable to update Umbrel through the web interface, follow these steps:

1. Restart your Umbrel.

2. If the issue persists, connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

3. Run the following command (“v0.5.3” example). If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   sudo ~/umbrel/scripts/update/update --repo getumbrel/umbrel#v0.5.3

   Replace “v0.5.3” with the release version you are trying to install. You can find the most recent releases here https://github.com/getumbrel/umbrel/releases (it will be at the top with a green highlight marking it latest)

Issues Installing Apps via Umbrel App Store

If you are unable to install an app through Umbrel app store, follow these steps:

1. Restart your Umbrel.

2. If the issue persists, connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

3. Run the following command. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   sudo ~/umbrel/scripts/stop && sudo ~/umbrel/scripts/start

4. Wait for the process to complete and try installing the app again through the Umbrel App Store.

External Hard Drive Connectivity Issue on Raspberry Pi

If you are having issues connecting your external hard drive, follow these steps:

1. Verify the USB cable connection between the Raspberry Pi and the external hard drive. Make sure the cable is plugged into the blue USB 3.0 port of your Raspberry Pi and is a proper USB 3.0 cable.

2. Restart your Umbrel.

3. If the issue still persists, generate your Umbrel’s troubleshooting logs by following the steps outlined in Generating Troubleshooting Logs.

4. Search the logs for the following lines in the “external storage service logs” section:

   Blacklisting USB device IDs against UAS driver...
USB devices weren't registered after 10 tries...

5. If you see any of the lines above, connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

6. Run the following command. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   sed -i 's/ blacklist_uas/ #blacklist_uas/g' ~/umbrel/scripts/umbrel-os/external-storage/mount && sudo reboot

Changing Your Umbrel Username

Changing the username via Umbrel’s UI is not currently possible, but is planned for a future release. In the meantime, you can follow these steps to change it via the command line:

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command*. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   echo "$( jq '.name = "NEWNAME"' ~/umbrel/db/user.json )" > ~/umbrel/db/user.json

   *Replace NEWNAME in the command above with your desired username (include the quotation marks surrounding your username).

Resolving "Failed to Start Containers" Error Message

If your Umbrel logs show an error message that reads “failed to start containers”, follow these steps:

1. Restart your Umbrel

2. If the problem persists, connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

3. Run the following command. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   cd ~/umbrel && sudo systemctl stop docker.service && sudo systemctl stop docker.socket && sudo rm -rf /var/lib/docker/* && sudo unmount /var/lib/docker || true && sudo rm -rf /mnt/data/docker/* && sudo reboot

This will stop and reset your docker service files and then it will reboot your device, which may take several minutes.

Apps - Troubleshooting & FAQ

Bitcoin Node (official Umbrel app)

Accessing bitcoin-cli

To access the command line interface for interacting with your Bitcoin node, follow these steps:

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command*. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   ~/umbrel/scripts/app compose bitcoin exec bitcoind bitcoin-cli <command>

   *Replace <command> with any of the bitcoin-cli commands, such as getblockchaininfo.

Locating the bitcoin.conf File

The latest version of the Bitcoin Node app does not include a bitcoin.conf file by default. Instead, you will have a file named umbrel-bitcoin.conf located at:

`~/umbrel/app-data/bitcoin/data/bitcoin/umbrel-bitcoin.conf`

This file should not be edited manually. Instead, configuration options in this file should be changed through “Advanced Settings” in the Bitcoin Node app.

If you would like to add configuration options to your node that are not present in “Advanced Settings”, you can create a bitcoin.conf file at the following path:

`~/umbrel/app-data/bitcoin/data/bitcoin/bitcoin.conf`

Add your required lines to this file, and then restart your Bitcoin node from the “Advanced Settings menu” in the Bitcoin Node app. Your new configuration options will be included in umbrel-bitcoin.conf.

Speeding Up Blockchain Synchronization

The easiest way to speed up the initial block download of your node is through “Advanced Settings” in the Bitcoin Node app. Follow these steps:

1. Open “Advanced Settings” within the Bitcoin Node app.

2. Increase the “Cache Size” setting in MB. Ensure that your device has enough RAM to support the increase in value.

3. (Optional) Enable “Outgoing Connections to Clearnet Peers” and disable “Connect to all Clearnet Peers over Tor” so your Bitcoin node is not throttled by Tor’s latency to fetch the blocks. Note: This will leak IP address to the Bitcoin network, and your ISP will also be able to figure out that you’re running a Bitcoin node. If you change these settings, you may revert them after the synchronizing is complete.

4. Click “Save and Restart Bitcoin Node”.

This will speed up your initial sync. Once your node is fully synced, reduce the cache size back to its default value of 450 MB and restart the node again through “Advanced Settings”.

How to Synchronize a New Bitcoin Node from an Existing One

Advanced users can take advantage of the following methods to synchronize a new node with an existing one. Please be cautious as these methods are not natively supported in Umbrel.

Method 1: Transferring Blockchain Data

The steps below are for copying data from an existing Linux machine to a new Raspberry Pi, but the steps are similar for other combinations of devices.

1. Flash UmbrelOS to a microSD card and boot the Raspberry Pi with your SSD attached.
2. Complete the Umbrel setup process. Your SSD will now be formatted for Umbrel use.
3. Go to the settings page and shut down Umbrel.
4. Remove the SSD and attach it to a Linux machine with the full blockchain.
5. Copy the blocks and chainstate directories on the Linux machine to ~/umbrel/app-data/bitcoin/data/bitcoin directory on the SSD.
6. Remove the SSD from your Linux machine, plug it back into your Raspberry Pi, and power it back on.

Method 2: Direct Synchronization

This method allows you to sync your new node from another running Bitcoin node on the same network or trusted connection, without the need to copy data to a different device.

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command*. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   sudo ~/umbrel/scripts/app compose bitcoin exec bitcoind bitcoin-cli addnode "192.168.x.x:8333" "onetry"

   *Replace “192.168.x.x” with the IP of the existing running node.

Once your new node is fully synced, you can safely remove the IP from peers and go back to a normal connection. For more information, see https://chainquery.com/bitcoin-cli/addnode.

Resolving Corrupted Blockchain Issues

Resolving a corrupted blockchain is a time-consuming process. Depending on the size of the blockchain and the speed of your device, this process can take several days. It is important to be patient and not interrupt the process, as interrupting it may result in needing to restart the process from the beginning.

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command to open bitcoin.conf in a nano text editor. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   sudo nano ~/umbrel/app-data/bitcoin/data/bitcoin/bitcoin.conf

3. Add the following line to the file:

   reindex=1

4. Save and exit the file by pressing CTRL+X, then Y, and then ENTER.

5. Restart your Bitcoin node by running the following command:

   sudo ~/umbrel/scripts/app restart bitcoin

Your Bitcoin node will now start the process of reindexing. You can monitor the reindexing progress of your node by accessing your Bitcoin Node app through the browser.

After your node is fully synced, follow the same steps to remove reindex=1 from the bitcoin.conf file and restart your Bitcoin Node. If you do not do this, then the lengthy process of reindexing will occur again the next time your node restarts.

Note: It may also take some time for dependant apps like Electrs to resume functioning after the reindex is the complete.

Lightning Node (official Umbrel app)

Accessing lncli

To access the command line interface for interacting with your Lightning node, follow these steps:

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command*. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   ~/umbrel/scripts/app compose lightning exec lnd lncli <command>

   *Replace <command> with any of the lncli commands, such as getinfo.

Locating the lnd.conf File

The latest version of the Lightning Node app does not include an lnd.conf file by default. Instead, you will have a file named umbrel-lnd.conf located at:

`~/umbrel/app-data/lightning/data/lnd/umbrel-lnd.conf`

This file should not be edited manually. Instead, configuration options in this file should be changed through “Advanced Settings” in the Lightning Node app.

If you would like to add configuration options to your node that are not present in “Advanced Settings”, you can create an lnd.conf file at the following path:

`~/umbrel/app-data/lightning/data/lnd/lnd.conf`

Add your required lines to this file, and then restart your Lightning Node app from the “Advanced Settings menu” in the Lightning Node app. Your new configuration options will be included in umbrel-lnd.conf.

Restoring Your Lightning Node and Payment Channels

To restore your Lightning node and payment channels, follow these steps:

1. Install/re-install the Lightning Node app
2. Select “Recover your previous node” when prompted
3. Enter your 24 secret words
4. Select an automatic encrypted backup of your channels or upload your own backup file, and that’s it. Here is a demo of the Automatic Channel Recovery tool.

Updating Your Lightning Node's Alias

The latest version of the Lightning Node app now allows you to easily change the alias of your Lightning node from the “Advanced Settings” menu! Navigate to the menu and change your alias, along with other desired configuration options, then save the changes by clicking “save and restart node”.

Resolving Offline Channels

If your Lightning channels have been showing as “Offline” for an extended period, follow these steps:

1. Check that you are running the latest version of the Lightning Node app, and update if necessary through the Umbrel App Store.

2. If your Lightning Node app is already up-to-date, you should restart your Umbrel from the main Umbrel “Settings” menu.

3. After app update or restart it may take several minutes to see your channels as “Online”.

If the above steps do not resolve your issue, you may need to follow the steps outlined in Rescanning Wallet UTXOs.

Rescanning Wallet UTXOs

Rescanning your wallet’s UTXO’s is a time-consuming process and may take upwards of 24 hours to complete.

1. Connect to your Umbrel device by following the instructions in How to SSH into Umbrel on a Raspberry Pi or by accessing a terminal on your Linux machine.

2. Run the following command. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in Troubleshooting on Linux:

   sed -i "s/\[Application Options\]/\[Application Options\]\nreset-wallet-transactions=true/g;" ~/umbrel/app-data/lightning/data/lnd/lnd.conf

3. Restart your Lightning Node app from the “Advanced Settings menu” in the Lightning Node app.

4. Wait for the rescanning process to complete.

5. Once complete, run the following command to ensure that the lengthy rescanning process does not occur again on subsequent restarts. If you are on a Linux machine, you may need to replace ~ with the path to your installation directory, as described in *Troubleshooting on Linux:

   sed -i "s/reset-wallet-transactions=true//g;" ~/umbrel/app-data/lightning/data/lnd/lnd.conf

6. Restart your Lightning Node app from the “Advanced Settings menu” in the Lightning Node app.