The deployment of a Nostr relay on Umbrel OS is designed to be a streamlined, one-click experience. However, the decentralized nature of the Nostr protocol, combined with the resource-intensive requirements of maintaining a relay, often leads to technical friction. Users frequently encounter issues ranging from “Relay Unreachable” errors to total synchronization stalls.
These issues typically stem from three areas: network configuration (Tor vs. Clearnet), hardware bottlenecks (I/O wait on storage), or containerized environment conflicts within the Umbrel Docker stack. This guide provides a deep technical dive into diagnosing and resolving these failures to ensure your relay maintains high uptime and NIP compliance.
What a Nostr Relay Error Actually Means
A Nostr relay is essentially a specialized server that accepts WebSocket connections, stores events in a database, and broadcasts them to connected clients based on filters. When an umbrel Nostr Relay fails, it is usually a breakdown in the communication between the client (like Damus, Amethyst, or Iris) and the relay’s entry point.
Technically, this involves the WebSocket (WSS) protocol. Unlike standard HTTP requests, WebSockets require a persistent, bidirectional connection. If the Umbrel middleware or the underlying Docker network cannot maintain this state—or if the database cannot write incoming events fast enough—the connection is dropped. On Umbrel, this often manifests as a “Connection Refused” error or a “Timeout” when a client attempts to fetch the relay’s NIP-11 information (the relay metadata).
Main Causes of Failure
1. Port Forwarding and Clearnet Accessibility
Most Umbrel instances run behind Tor by default. While this provides privacy, many Nostr clients struggle with Tor latency or lack native Tor support. If you are trying to reach your relay via a clearnet URL or your public IP, you must have port forwarding correctly configured on your router.
2. Database I/O Bottlenecks
Nostr relays are heavy on “writes.” As global event volume increases, the relay must constantly write to its database (often PostgreSQL, SQLite, or LMDB depending on the specific app version). If you are running Umbrel on a Raspberry Pi using a MicroSD card or a slow external HDD, the I/O Wait will spike, causing the relay process to hang or crash.
3. Docker Network Isolation
Umbrel operates using Docker containers. Occasionally, the internal bridge network fails to route traffic from the Umbrel Nginx proxy to the specific Nostr relay container. This results in the app appearing “Started” in the dashboard but being unreachable via its assigned port.
4. Memory Exhaustion (OOM)
Relays that do not implement strict “event deletion” or “max event size” policies can quickly consume available RAM. On 4GB Raspberry Pi models, the Linux kernel’s Out-Of-Memory (OOM) Killer may terminate the relay process to save the OS.
Step-by-Step Fix
Step 1: Accessing the Logs
Before changing settings, you must identify the specific error. Access your Umbrel via SSH:
ssh umbrel@umbrel.local
Once logged in, navigate to the app directory and view the real-time logs for the Nostr Relay. (Note: The exact directory name may vary depending on whether you are using the official Nostr Relay app or a third-party version like “Relay”):
cd ~/umbrel/app-data/nostr-relay
docker-compose logs -f --tail=100
What to look for:
Error: Database is locked: Indicates a storage speed issue or a corrupted index.EADDRINUSE: Another process is trying to use the same port.Connection reset by peer: Likely a networking/firewall issue.
Step 2: Verifying Port Configuration
For your relay to be accessible over the internet (Clearnet), you must ensure port 2100 (or the port specified in your app’s settings) is open.
- Check if the port is listening locally:
sudo lsof -i -P -n | grep LISTEN - Log into your router’s gateway.
- Forward TCP port 2100 (and 80/443 if using a reverse proxy) to the local IP address of your Umbrel.
Step 3: Repairing the Database
If logs show database corruption, you may need to re-index. For relays using PostgreSQL, you can enter the container to run a vacuum:
docker exec -it nostr-relay_db_1 vacuumdb -U postgres -d nostr_relay_db
If the corruption is severe, you may need to wipe the data and resync. Warning: This deletes all stored events on your relay.
- Stop the app in the Umbrel dashboard.
- Delete the data folder:
rm -rf ~/umbrel/app-data/nostr-relay/data/db - Restart the app.
Step 4: Optimizing Resource Usage
If your relay is crashing due to memory issues, you can limit its usage by editing the docker-compose.yml file in the app directory, though this is an advanced step. A safer method is to increase the Swap File size on your Umbrel to provide a buffer for RAM spikes.
sudo /home/umbrel/umbrel/scripts/configure-swap.sh --size 4096
When it’s a Hardware Limitation
Running an umbrel Nostr Relay is significantly more demanding than running a Bitcoin node. If you continue to see “Slow Write” warnings in your logs, your hardware is likely the bottleneck.
SSD vs. MicroSD
Running a relay on a MicroSD card is not sustainable. The high frequency of small write operations will wear out the flash memory within months and cause massive latency. You must use an SSD (NVMe is preferred over SATA via USB) to handle the database overhead.
Raspberry Pi vs. Mini PC
While a Raspberry Pi 4 (8GB) can handle a low-traffic private relay, it will struggle with a public relay that has hundreds of concurrent connections.
- Raspberry Pi 4/5: Best for private use or small circles of friends.
- Mini PC (Intel NUC / Ryzen): Required for public relays. The higher single-core CPU clock speed is vital for processing WebSocket messages and JSON parsing.
When Reinstalling is Necessary
If you have updated Umbrel OS and the Nostr Relay app fails to start entirely, or if you see “Manifest not found” errors, a clean reinstall is often the fastest path to resolution.
- Uninstall the app via the Umbrel App Store.
- SSH into the device and ensure the directory is gone:
rm -rf ~/umbrel/app-data/nostr-relay. - Reboot the Umbrel:
sudo reboot. - Reinstall from the App Store.
This process clears the Docker cache and ensures any changes in the app’s internal networking requirements are correctly applied.
How to Prevent Future Issues
To ensure your Nostr relay remains stable:
- Monitor Disk Space: Nostr events are small, but they add up. Check your storage via the Umbrel dashboard regularly.
- Limit Event Age: If your relay software allows it, set a “Max Event Age” (e.g., 30 days) to prevent the database from ballooning.
- Use a UPS: Sudden power cuts are the primary cause of database corruption in Umbrel. An Uninterruptible Power Supply (UPS) ensures the database can close connections safely during a blackout.
- Set Connection Limits: If your relay is public, restrict the number of concurrent WebSocket connections to prevent a single bot from exhausting your RAM.
FAQ
Q: Can I run a Nostr relay on Ubuntu without Umbrel? A: Yes. Many users prefer installing nostr-rs-relay or strfry directly on Ubuntu via Docker or binary to avoid the overhead of the Umbrel UI. However, you lose the ease of management provided by the Umbrel dashboard.
Q: Why is my Nostr relay not visible on the network? A: This is usually due to missing port forwarding or a firewall (ufw) on the Umbrel device blocking incoming traffic. Ensure port 2100 is open and that your router is not using CGNAT.
Q: How much storage does a Nostr relay need? A: A private relay needs very little (<10GB). A public relay with no filters can easily consume 100GB+ in a few months depending on the “Global” feed traffic.
Q: Does Umbrel support NIP-05? A: NIP-05 (DNS-based verification) is handled at the domain level, not the relay level. You can host your well-known file on Umbrel using the “Static Site” app or a similar web server, but it is technically independent of the relay app.
Technical Conclusion
Troubleshooting an umbrel Nostr Relay requires a methodical approach to identifying whether the failure point is the network layer, the database, or the hardware. By utilizing SSH to inspect Docker logs and ensuring your network environment supports persistent WebSocket connections, you can maintain a high-performance node. For most users, transitioning from a Raspberry Pi to a dedicated Mini PC and moving from Tor to Clearnet are the two most impactful upgrades for relay stability.
Internal Linking Suggestions: