Troubleshooting

Real errors, real fixes. All error strings below are verbatim from ferminux-geth (geth v1.10.26 lineage).

DAG generation

Symptom: node says Generating DAG in progress and mining doesn't start for a minute or two after the first --mine start (or after an epoch change).

This is normal Ethash. The miner needs the full dataset ("DAG") in memory/on disk; verifying-only nodes just need the small cache.

Epoch 0 DAG ≈ 1 GiB, generated in ~1–2 minutes on a modern CPU (Apple Silicon / recent x86). GPUs build it in seconds.
One epoch = 30,000 blocks ≈ 2.5 days at 7.2 s blocks, and the DAG grows ~8 MiB per epoch → about +1.1 GiB per year: ~2.1 GiB after year 1, ~3.3 GiB after year 2. Size your GPU/disk accordingly — a 4 GB GPU lasts roughly 2.5 years.
Generated DAGs are stored in ~/.ethash (Linux), ~/Library/Ethash (macOS), %LOCALAPPDATA%\Ethash (Windows) — note this is outside the datadir, so in Docker a recreated miner container regenerates it unless you mount a volume for /root/.ethash.
The client keeps DAGs for the current and next epoch; brief CPU spikes every ~2.5 days as the next one pre-generates are expected.

Peers stay at 0

ferminux-geth attach --exec 'net.peerCount'

If this stays 0:

Bootnode ceremony status — the most likely cause today. The built-in FerminuxBootnodes list ships empty; the production enode URLs are generated on boot1/boot2/boot3.ferminux.net at the mainnet infrastructure ceremony and baked into the first public release. Until you run a build with them included, a node has nobody to ask for peers — pass them explicitly:
```
ferminux-geth --bootnodes "enode://<key>@boot1.ferminux.net:30303,enode://<key>@boot2.ferminux.net:30303"
```
Current enodes are published at ferminux.net.
UDP blocked. Discovery is UDP on the same port as TCP (default 30303). Open both 30303/tcp and 30303/udp on your firewall/NAT.
Wrong network flags. Don't pass --mainnet, --sepolia, etc. — they still parse on this client but are non-functional; run with no network flag (Ferminux is the default).
Devnet-specific: the compose files pin --netrestrict 10.39.61.0/24; a node outside that subnet will be ignored by devnet peers by design.

Note: a node with peers but no new blocks on a young network may simply mean nobody is mining right now — check eth.blockNumber against the explorer.

`Fatal: invalid command-line: too many arguments` (flag order)

This geth line uses urfave/cli v1: flags must come BEFORE positional arguments. Anything after the first positional is rejected — that's this error (from attach / console), or for init:

Fatal: need genesis.json file as the only argument

# WRONG — flag after the socket path
ferminux-geth attach ~/.ferminux/geth.ipc --exec 'eth.blockNumber'
# Fatal: invalid command-line: too many arguments

# RIGHT — flags first, positional last
ferminux-geth attach --exec 'eth.blockNumber' ~/.ferminux/geth.ipc

# WRONG / RIGHT for init (init is optional — genesis is baked in — but if you run it):
ferminux-geth init genesis.json --datadir ~/.ferminux      # WRONG
ferminux-geth init --datadir ~/.ferminux genesis.json      # RIGHT

`attach` can't find the socket

Fatal: Unable to attach to remote geth: dial unix ...: connect: no such file or directory

The IPC socket is geth.ipc (kept from upstream for tooling compatibility) and lives at the top level of the datadir — not inside the ferminux-geth/ instance subdirectory:

OS	Socket path
Linux	`~/.ferminux/geth.ipc`
macOS	`~/Library/Ferminux/geth.ipc`
Custom `--datadir /data`	`/data/geth.ipc`

ferminux-geth attach                                  # finds it via the default datadir
ferminux-geth attach --exec 'eth.blockNumber' /data/geth.ipc   # explicit path
ferminux-geth attach --datadir /custom/dir            # non-default datadir, no explicit path

If you started the node with --ipcdisable, there is no socket — use ferminux-geth attach http://127.0.0.1:8545 against the HTTP endpoint instead.

Windows: named pipe caveat

On Windows the IPC endpoint is a top-level named pipe, \\.\pipe\geth.ipc — it is datadir-independent. Consequences:

attach with no argument connects to whichever client owns that pipe. On a machine that also runs vanilla geth, you can silently attach to the wrong client. Check the console banner (it says Ferminux-Geth) or run eth.chainId() → expect 3961.
Don't run ferminux-geth and vanilla geth simultaneously on Windows unless one of them gets --ipcpath with a distinct pipe name (or --ipcdisable).

Unix is unaffected: the socket lives inside the per-network datadir.

Chain data isn't where my backup script looks

Chain data lives in <datadir>/ferminux-geth/ (the instance directory follows the client name), e.g. ~/.ferminux/ferminux-geth/chaindata. Tooling that assumes upstream's geth/chaindata must be updated. The keystore is unchanged at <datadir>/keystore.

`Fatal: Failed to start mining: etherbase missing: etherbase must be explicitly specified`

--mine needs a payout address. Pass --miner.etherbase 0xYourAddress (the repo scripts enforce this via the FMX_REWARD_ADDR env var). If the node has a local keystore account, the first account is used automatically — but an explicit etherbase is the safer habit.

Signatures rejected / wrong chain replays

Any signer that defaults to Ethereum mainnet produces invalid signatures here. Ferminux is chain-id 3961 (EIP-155 active from genesis). clef in particular defaults to chain-id 1 — run it with --chainid 3961.

RPC works locally but not from another machine

By design. --http.addr defaults to 127.0.0.1. Do not flip it to 0.0.0.0 on an internet-facing box — put a reverse proxy with TLS and rate limiting in front, and never expose the personal/admin/debug/miner namespaces. See the security section of run-a-node.md.