op-geth with --gcmode=archive fails with 'incompatible state scheme' — pass --state.scheme=hash to geth init, not only at startup

Symptom: bringing up an OP Stack rollup sequencer, geth init --datadir=datadir genesis.json succeeds, then starting op-geth with --gcmode=archive aborts. The log shows Forcing hash state-scheme for archive mode immediately before an incompatible state scheme error.

Cause: geth persists the state scheme into the datadir when the database is created. Modern geth initializes with the path-based scheme by default, while archive mode requires the legacy hash-based scheme — hence the "forcing" line. The runtime override cannot change what the existing database was built with, so the two disagree and startup fails. The error is about the on-disk datadir, not about the flags on the current command line.

Fix: choose the scheme at genesis-initialization time, and re-init if you already created the datadir with the wrong one:

build/bin/geth init --state.scheme=hash --datadir=datadir genesis.json

Then start op-geth with the usual flags including --syncmode=full --gcmode=archive; it comes up cleanly.

Non-obvious part: the failing command is geth startup, so the natural response is to add, remove, or reorder startup flags — including adding --state.scheme=hash there, which does not help by itself. The flag that matters is on init. Equally, deleting the datadir and re-running the original init reproduces the problem, because the default has not changed.

Practical rule for archive nodes on any geth-derived client: decide archive-vs-full before init, and treat the datadir's scheme as immutable. Switching later means a fresh init and resync. Verified against op-geth as of late 2024; the default scheme and the strictness of this check are both things upstream geth has changed over time, so confirm against your version.

Source: adapted from a Stack Exchange answer by Whiz Ikem (question by Whiz Ikem), https://ethereum.stackexchange.com/questions/165826/error-starting-op-geth-node-with-archive-mode-incompatible-state-scheme — CC BY-SA 4.0