Troubleshooting

Issues concerning the primary operations of your Umbrel node.

General questions and further learnings regarding the technology used in Umbrel can be found in the separate General FAQ.

Can I login using SSH?
Is my Raspberry Pi compatible?
My Umbrel node keeps crashing. What can I do to fix the issue?
My Umbrel node doesn’t boot. What can I do?
I can’t access the dashboard at umbrel.local or my node keeps crashing. What can I do?
I want to connect to my node using …… over my local network, but it doesn’t work. How can I fix this?
Setting a fixed address on the Raspberry Pi
Using WiFi instead of Ethernet
Manually accessing bitcon-cli and lncli
Reset your Umbrel user data (if you lost your password)
Manually updating Umbrel
Recovering from a channels.backup (Umbrel OS)
Lightning node renaming
Rescan wallet UTXOs procedure
One Umbrel App do not start or it can’t be installed

Yes! Open a terminal on your computer and enter ssh umbrel@umbrel.local, the password is moneyprintergobrrr. On version 0.3.3 or later, the password is your personal user password instead.

Is my Raspberry Pi compatible?

If you have a Raspberry Pi with at least 4GB of RAM, you can run Umbrel on it.

My Umbrel node keeps crashing. What can I do to fix the issue?

If you’re not using the official power supply, it’s probably the power supply. To detect undervoltage, connect to your RPi via SSH and run this command: vcgencmd get_throttled. If it doesn’t output throttled=0x0, then it’s either the power supply or your SSD is using too much power (this can only be the case if you’re not using the recommended hardware).

If that doesn’t help, contact us on Telegram.

My Umbrel node doesn’t boot. What can I do?

Do you have connected anything to the GPIO pins? If yes, try to unplug it and reboot the RPi by unplugging the power supply and then plugging it back in.

I can’t access the dashboard at umbrel.local or my node keeps crashing. What can I do?

Check if your router detects your node. If it doesn’t, either you ethernet cable isn’t plugged in correctly or the node doesn’t boot. If you think the ethernet cable isn’t the issue, follow the answer of the previous question.

If it does detect the node, try to access it with the IP address directly. If you can’t access the dashboard via the IP address either, try to run an automatic issue finding tool over SSH:

~/umbrel/scripts/debug --upload

It’ll automatically tell you the next step.

I want to connect to my node using …… over my local network, but it doesn’t work. How can I fix this?

If you want to connect to your Umbrel over the local network just replace your onion domain with umbrel.local for any of the connection strings.

Setting a fixed address on the Raspberry Pi

If your router does not support setting a static ip address for a single device, you can also do this directly on the Raspberry Pi.

This can be done by configuring the DHCP-Client (on the Pi) to advertise a static IP address to the DHCP-Server (often the router) before it automatically assigns a different one to the Raspberry Pi.

Get ip address of default gateway (router). Run netstat -r -n and choose the IP address from the gateway column which is not 0.0.0.0. In my occasion it’s 192.168.178.1.
Configure the static IP address for the Pi, the gateway path and a DNS server. The configuration for the DHCP client (Pi) is located in the /etc/dhcpcd.conf file:
```
sudo nano /etc/dhcpcd.conf
```
The following snippet is an example of a sample configuration. Change the value of static routers and static domain_name_servers to the IP of your router (default gateway) from step 1. Be aware of giving the Raspberry Pi an address which is OUTSIDE the range of addresses which are assigned by the DHCP server. You can get this range by looking under the router configurations page and checking for the range of the DHCP addresses. This means, that if the DHCP range goes from 192.168.178.1 to 192.168.178.99 you’re good to go with the IP 192.168.178.100 for your Raspberry Pi.

Add the following to the /etc/dhcpcd.conf file:
```
# Configuration static IP address (CHANGE THE VALUES TO FIT FOR YOUR NETWORK)
interface eth0
static ip_address=192.168.178.100/24
static routers=192.168.178.1
static domain_name_servers=192.168.178.1
```
Restart networking system sudo /etc/init.d/networking restart

Using WiFi instead of Ethernet

Create a file wpa_supplicant.conf in the boot partition of the microSD card with the following content. Note that the network name (ssid) and password need to be in double-quotes (like psk="password")
```
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=[COUNTRY_CODE]
network={
  ssid="[WIFI_SSID]"
  psk="[WIFI_PASSWORD]"
}
```
Replace [COUNTRY_CODE] with the ISO2 code of your country (eg. US)
Replace [WIFI_SSID] and [WIFI_PASSWORD] with the credentials for your own WiFi.

Manually accessing `bitcon-cli` and `lncli`

On Umbrel, these binaries are always available in UMBREL_ROOT_DIR/bin/. On Umbrel OS, you can access them over SSH as

~/umbrel/bin/bitcoin-cli

and

~/umbrel/bin/lncli

Reset your Umbrel user data (if you lost your password)

Do this only if you do not have any funds on your LND wallet! If you have funds, then save your seed + backup file so you are able to restore it later if needed.

You are going to loose your seed, settings, data and applications!

sudo systemctl stop umbrel-startup && sudo rm -rf ~/umbrel/lnd/!(lnd.conf) && sudo rm ~/umbrel/db/user.json && sudo rm ~/umbrel/db/umbrel-seed/seed && sudo systemctl start umbrel-startup

Manually updating Umbrel

To manually update your node, run these commands over SSH:

cd ~/umbrel && sudo ./scripts/update/update --repo getumbrel/umbrel#v0.3.7

Replace v0.3.7 with the version you want to update to.

If the update was stuck, run this before the above command:

sudo rm statuses/update-in-progress

Recovering from a channels.backup (Umbrel OS)

Once you’ve restored from the 24 words, it might take a few minutes to a few hours for it to scan all of your previous Bitcoin (on-chain) transactions and balances. Meanwhile, here’s how you can restore the funds in your Lightning channels.

Step 1: Copy over the channel backup file from your computer to your Umbrel.

Open the “Terminal” app on Mac/Linux, or “PowerShell” on Windows and run this:

scp <path/to/your/channel/backup/file> umbrel@umbrel.local:/home/umbrel/umbrel/lnd/channel.backup

(Replace <path/to/your/channel/backup/file> with the exact path to channel backup file on your computer)

The password is moneyprintergobrrr, except on version 0.3.3 or later where the password is your personal user password instead.

Step 2: SSH into your Umbrel

This is explained here.

Step 3: Recover funds

cd ~/umbrel && ./bin/lncli restorechanbackup --multi_file /data/.lnd/channel.backup

After you run this, wait for 1 minute. You should now be able to see your channels being closed on http://umbrel.local/lightning.

Lightning node renaming

Please keep the following security disclaimer in mind (by @mayankchhabra, the founder of Umbrel):

Aliases can do more harm than good by leaking your private info (h/t @lukechilds for bringing this up when we were considering setting default aliases as ’s Umbrel). Imagine you name your alias “Lounès’s Umbrel”. I can then go to [1ml.com](https://1ml.com), instantly find your node, see your balance, open channels, etc. There isn’t much of an upside of setting a custom alias for private use as aliases aren’t unique and you can’t directly open channels by just using them as you still need the public key (and the onion address if it’s a Tor node). They have more value for bigger nodes (usually businesses) like Bitrefill, Bitfinex, etc so you can instantly find them and open a channel.

By this you can rename your LN node via SSH, so you do not have random name.

sudo nano ~/umbrel/lnd/lnd.conf

Add alias=My amazing node just after [Application Options]

  [Application Options]
  alias=My amazing node
  listen=0.0.0.0:9735
  rpclisten=0.0.0.0:10009

Save the file using Ctrl + X and y

Restart your node: sudo systemctl restart umbrel-startup

NOTICE: keep a copy of this lnd.conf file. After Umbrel update this file will be overwritten. So after a software update put the lnd.conf file back from your copy.

Rescan wallet UTXOs procedure

I sent funds to my node wallet and wasn’t 100% synced, now I can’t see them.

Step 1 - In a terminal window, execute this to SSH:

ssh -t umbrel@umbrel.local

Password: < your own dashboard password > (remember that you will not see what you type, then press ENTER)

Step 2 - execute the following command to rescan wallet’s UTXOs:

sed -i "s/\[Application Options\]/\[Application Options\]\nreset-wallet-transactions=true/g;" ~/umbrel/lnd/lnd.conf && sudo reboot

Step 3 - Wait some time so LND can rescan all wallet’s UTXOs. If it solve the issue, run this to stop it from rescanning on a future restart:

sed -i "s/reset-wallet-transactions=true//g;" ~/umbrel/lnd/lnd.conf && sudo reboot

Wait, it can take quite a while.

One Umbrel App do not start or it can’t be installed

If you have error that a specific Umbrel App do not start or it keeps staying in “installing”, maybe the docker container for that app it wasn’t installed correctly or it hangs.

Step 1 - In a terminal window, execute this to SSH:

ssh -t umbrel@umbrel.local

Password: < your own Umbrel dashboard password > (remember that you will not see what you type, then press ENTER)

Step 2 - stop Umbrel node with:

sudo ./scripts/stop

Step 3 - clean / reconfigure the broken container:

sudo rm .env && sudo ./scripts/configure

Step 4 - apply latest Umbrel update (replace the version number with the latest):

sudo ./scripts/update/update --repo getumbrel/umbrel#v0.3.10

Restart your node:

sudo ./scripts/start

You can open Umbrel dashboard, but wait until latest blocks are catching up and also electrs is synced. All txs and channels will appear after a while.

This troubleshooting guide will be constantly updated with findings that have been or will be reported in the issues section. Feel free to contribute via a merge request.