Umbrel – Troubleshooting

TABLE OF CONTENTS

1. Can I login using SSH?
2. Is my Raspberry Pi compatible?
3. My Umbrel node keeps crashing. What can I do?
4. My Umbrel node doesn’t boot. What can I do?
5. I can’t access the dashboard at umbrel.local or my node keeps crashing
6. Setting a fixed address on the Raspberry Pi
7. Using WiFi instead of Ethernet
8. Manually accessing `bitcon-cli` and `lncli`
9. Reset your Umbrel user data (if you lost your password)
10. Manually updating Umbrel
11. Recovering from a channels.backup (Umbrel OS)
12. Lightning node renaming
13. Rescan wallet UTXOs procedure
14. One Umbrel App do not start or it can’t be installed

1. Can I login using SSH?

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.

2. Is my Raspberry Pi compatible?

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

3. 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 or post on Umbrel Community Forum your issue.

4. 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.

5. 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.

Optional guide here, if is just a matter of DHCP assigned IP.

6. 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.

1. 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

2. 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

3. Restart networking system with: sudo /etc/init.d/networking restart

7. 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](https://www.iso.org/obp/ui/#search) of your country (eg. `US`)
* Replace `[WIFI_SSID]` and `[WIFI_PASSWORD]` with the credentials for your own WiFi.

8.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

9. 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

10. Manually updating Umbrel

To manually update your node, run these commands over SSH:
cd ~/umbrel && sudo ./scripts/update/update --repo getumbrel/umbrel#v0.3.14

Replace v0.3.14 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

11. 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

Explained here, how to

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.

12. 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 with: 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.

13. 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.

14. 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.14

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.