Start9 Electrs Startup Failure After StartOS Upgrade

**Date:** 25 July 2026
## Summary
After upgrading StartOS, the **Electrs** service failed to start on **both** Start9 servers.
The issue was **not** related to the Bitcoin blockchain, Electrs index, SSD, hardware or network. The root cause was a configuration conflict introduced during the migration process.
---
# Affected Systems
## Server 1
- Hardware: AMD Ryzen 7 5825U
- Bitcoin implementation: Bitcoin Knots
- Electrs version: 0.11.1
## Server 2
- Hardware: Intel Celeron N4505
- Bitcoin implementation: Bitcoin Core
- Electrs version: 0.11.1
Both systems exhibited the identical failure immediately after the StartOS upgrade.
---
# Symptoms
Electrs repeatedly exited during startup.
The log reported:
```
Error: ambiguous configuration - auth and cookie_file can't be specified at the same time
```
---
# Investigation
The Electrs configuration file was located at:
```
/media/startos/data/package-data/volumes/electrs/data/main/electrs.toml
```
Its contents were:
```toml
cookie_file = "/mnt/bitcoind/.cookie"
daemon_rpc_addr = "10.0.3.1:63174"
daemon_p2p_addr = "10.0.3.1:58334"
network = "bitcoin"
electrum_rpc_addr = "0.0.0.0:50001"
log_filters = "INFO"
auth = "bitcoin:xxxxxxxxxxxxxxxx"
```
Electrs accepts **either**
- cookie authentication
or
- username/password authentication
but **not both simultaneously**.
The migration left both options in the configuration.
---
# Resolution
Create a backup:
```bash
sudo cp \
/media/startos/data/package-data/volumes/electrs/data/main/electrs.toml \
/media/startos/data/package-data/volumes/electrs/data/main/electrs.toml.backup
```
Remove only the `auth` line:
```bash
sudo sed -i '/^auth = /d' \
/media/startos/data/package-data/volumes/electrs/data/main/electrs.toml
```
Verify:
```bash
sudo nl -ba \
/media/startos/data/package-data/volumes/electrs/data/main/electrs.toml
```
Correct result:
```toml
cookie_file = "/mnt/bitcoind/.cookie"
daemon_rpc_addr = "10.0.3.1:63174"
daemon_p2p_addr = "10.0.3.1:58334"
network = "bitcoin"
electrum_rpc_addr = "0.0.0.0:50001"
log_filters = "INFO"
```
Restart the Electrs service from the StartOS interface.
Electrs started immediately without rebuilding the index.
---
# Root Cause
A StartOS migration bug appears to leave the legacy
```toml
auth = "bitcoin:..."
```
entry in `electrs.toml` while simultaneously enabling
```toml
cookie_file = "/mnt/bitcoind/.cookie"
```
This produces an invalid Electrs configuration.
---
# Evidence
- Reproduced on **two independent Start9 servers**
- Different hardware platforms
- Different Bitcoin implementations (Core and Knots)
- Identical configuration conflict
- Identical error message
- Identical fix
This strongly indicates a migration bug rather than a hardware or installation issue.
---
# Lessons Learned
- Do **not** delete the Electrs database.
- Do **not** resync Bitcoin.
- Do **not** rebuild the Electrs index.
Always inspect:
```
/media/startos/data/package-data/volumes/electrs/data/main/electrs.toml
```
If both `cookie_file` and `auth` are present, remove only the `auth` entry.
---
# Recommendation
Report the issue to the Start9 developers with:
- StartOS version
- Electrs version
- Exact error message
- Original `electrs.toml`
- Corrected `electrs.toml`
- Confirmation that the issue occurred on two separate servers and was resolved by removing the `auth` line.