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.