Official Umbrel Troubleshooting Guide and FAQ

Guides
1

Overview

Facing an issue with your umbrelOS 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 the official Umbrel Discord 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 the official Umbrel Discord 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 :speech_balloon: 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 your 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 umbrelOS, but we recommend 8GB of RAM for optimal performance (especially if running multiple apps in the Bitcoin ecosystem). Raspberry Pi 5 compatibility is coming soon, so stay tuned! Unfortunately, the Raspberry Pi 3 is not compatible with umbrelOS as it only supports 32-bit operating systems (umbrelOS is a 64-bit operating system).

Migrating from Raspberry Pi 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.

Installing umbrelOS on Non-Raspberry Pi Hardware

You can install umbrelOS 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.

Alternatively, you can buy the official Umbrel Home, a compact, powerful, and plug and play home server that’s designed for umbrelOS and comes pre-installed with it.

Disk space requirements

The disk space you need ultimately depends upon your use-case. umbrelOS, in itself, only requires about ~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 550GB 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 umbrelOS on Umbrel Home or Rasberry Pi

SSH (Secure Shell) is a way to access and control a device, such as your Umbrel server running on a Umbrel Home or 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 on Raspberry Pi, and umbrel on Umbrel Home. 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/known_hosts

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

Here’s a helpful guide on how that looks!

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 ~/umbrel with the actual path to the Umbrel folder in the commands provided in this guide.

For example, you would replace ~/umbrel 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 server through a web browser, you can generate troubleshooting logs from the command line by following these steps:

  1. Connect to your Umbrel server by following the instructions in How to SSH into umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel 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 server by following the instructions in How to SSH into umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel 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 ID of the app you want to view the logs for. The list of app IDs 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, the official Umbrel Discord, or with the Umbrel team using the chat icon :speech_balloon: located at the bottom right of Umbrel.com.

Raspberry Pi Not Powering On

If your Raspberry Pi will not power on/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 :speech_balloon: located at the bottom right of umbrel.com.

Unable to Access your Umbrel via Web Browser at umbrel.local

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”, and not down its IP address. Then try visiting that IP address directly in your web browser.

Alternatively, use an app like Angry IP Scanner to scan your local devices and figure out your Umbrel server’s IP address.

If you still cannot find your Umbrel’s IP, make sure:

  1. The Ethernet cable is properly plugged in.
  2. Your device (eg. Raspberry Pi, Umbrel Home, etc) is turned on.

Some more tips:

  • Double-check that the device you’re trying to access it from is connected to the same network as your Umbrel server.

  • Manually type “http://” before “umbrel.local” (without quotes) in your browser. If you’re on Windows, try http://umbrel instead.

  • If you’re using a VPN, try disabling it temporarily.

  • Try accessing http://umbrel.local on another device connected to the same network.

If you still cannot access your Umbrel server, please connect directly with the Umbrel team using the chat icon :speech_balloon: 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’re using Umbrel Home, please contact the Umbrel team using the chat icon :speech_balloon: located at the bottom right of umbrel.com to get assistance.

For Raspberry Pi and 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 umbrelOS on Umbrel Home or Rasberry 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 $HOME/umbrel with the path to your installation directory, as described in Troubleshooting on Linux:

    json_file="$HOME/umbrel/db/user.json" && contents="$(jq 'del(.otpUri)' ${json_file})" && echo "${contents}" | sudo tee ${json_file}

This will disable 2FA.

Issues Updating Umbrel via Web Browser

If you are unable to update Umbrel through the web interface, restart your Umbrel from settings and try updating again. If the issue persists, please contact the Umbrel team directly using the chat icon :speech_balloon: located at the bottom right of umbrel.com.

Cannot install an app in the 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 umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel 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.

Cannot find an app in the Umbrel App Store

If for any reason apps are not loading in your App Store, or you don’t see certain applications populating correctly, run the following command. If you are on a Linux machine, you may need to replace ~/umbrel with the path to your installation directory, as described in Troubleshooting on Linux:

sudo rm -f ~/umbrel/repos/https---github-com-getumbrel-umbrel-apps-git/.git/index.lock && sudo rm -f ~/umbrel/repos/https---github-com-getumbrel-umbrel-apps-git/.git/ORIG_HEAD.lock && sudo ~/umbrel/scripts/repo update

Then wait ~2 minutes, refresh your browser, and try visiting the app store again.

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 compatible USB 3.0 cable.

  2. Restart your Umbrel from the settings.

  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 server by following the instructions in How to SSH into umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel 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

Resolving “Error: System service failed”

This error is the result of several issues usually occurring on Raspberry Pi 4 devices and related to the MicroSD card and/or a read/write issue with the installed storage drive that we can isolate and resolve.

Please follow the handy guide here on resolving this issue!

Resolving "Failed to Start Containers" Error Message

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

  1. Restart your Umbrel server from settings.

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

  3. Run the following command:

    sudo systemctl stop docker && sudo rm -rf /var/lib/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 umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel with the path to your installation directory, as described in Troubleshooting on Linux:

    sudo ~/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`

If you are on a Linux machine, you may need to replace ~/umbrel with the path to your installation directory, as described in Troubleshooting on Linux.

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 umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel 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

You may see an error in your log that looks like this:

LevelDB read failure: Corruption: block checksum mismatch: /data/.bitcoin/chainstate/1066593.ldb

*The digits may be different, or there may be another issue requesting you to reindex.

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 umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel 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.

Resolving “corrupt peers.dat" error

If you see this error in your debug log:

Error: Invalid or corrupt peers.dat (Checksum mismatch, data corrupted)

You can resolve this error with these steps!

Resolving “Error: Failed loading settings file/Unable to parse settings file”

If you check your debug logs you may have the following:

"Error: Failed loading settings file:

bitcoind_1 | - Unable to parse settings file /data/.bitcoin/settings.json "

To resolve, first connect to your Umbrel server by following the instructions in How to SSH into umbrelOS on Umbrel Home or Rasberry Pi or by accessing a terminal on your Linux machine

This command is the quickest way to resolve the error, by deleting the file first:
sudo rm ~/umbrel/app-data/bitcoin/data/bitcoin/settings.json (replace ~/umbrel with path to your umbrelOS installation directory if not on a Raspberry Pi or Umbrel Home).

Then you should restart Bitcoin:

sudo ~/umbrel/scripts/app restart bitcoin

Upon restarting, wait ~5 minutes and this will resolve the error with the settings.json file.

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 umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel with the path to your installation directory, as described in Troubleshooting on Linux:

    sudo ~/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 more than 24 hours to complete.

  1. Connect to your Umbrel server by following the instructions in How to SSH into umbrelOS on Umbrel Home or Rasberry 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 ~/umbrel 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 by clicking the “Save and restart” button.

  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 ~/umbrel 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 by clicking the “Save and restart” button.

8 Likes