Hyperliquid node crash after the October 2026 hardfork: missing node_metadata.json

Hyperliquid mainnet upgraded at block 1196574000 on 25 October 2026, 09:32 UTC. Non-validator nodes running an hl-visor older than September 2026 crash on every start after the upgrade. This page shows how to recognize it, why it happens and the five-minute fix. The same failure is reported in hyperliquid-dex/node issue #182.

The short version#

• Symptom: the node panics with failed to validate hardfork version: missing file: ... node_metadata.json and never applies a block.
• Cause: hl-visor upgraded hl-node to binary 115, but the visor itself is old. Only a current visor writes node_metadata.json.
• Fix: download the current hl-visor, verify its signature, replace the binary, start the service. No resync.

1. Symptoms#

The supervisor journal shows the child being restarted every few minutes, and the node never writes an applied block line:

hl-visor @@ downloading new hl-node binary @@ [chain: Mainnet] @ [prev_downloaded_index: 114]
hl-visor @@ restarting child @@ [active_binary_height: 115]
hl-node @@ using local AbciState: missing
hl-visor @@ visor child in bad state, restarting @@ [child_stuck: false]

The real error is in the child's stderr log under ~/hl/data/visor_child_stderr/<date>/115/. Every file there ends the same way:

thread 'main' panicked at node/src/startup.rs:60:21:
failed to validate hardfork version: missing file: /root/hl/hyperliquid_data/node_metadata.json

Count the crashes to confirm it is this loop and not a one-off:

grep -rl "failed to validate hardfork version" ~/hl/data/visor_child_stderr/ | wc -l
ls ~/hl/hyperliquid_data/node_metadata.json   # "No such file" on an affected node

The node also downloads a fresh state snapshot from a peer on each start. During the upgrade window many peers answer Peer full, so the logs look like a peering problem. Peers are not the cause.

2. Cause#

hl-visor is the supervisor. It downloads each new hl-node binary, verifies it with Hyperliquid's key and restarts the node on it. It never replaces its own binary. At the hardfork it moved nodes to hl-node binary 115, which validates the hardfork version against hyperliquid_data/node_metadata.json at startup. A current hl-visor writes that file. An hl-visor from before September 2026 does not, so binary 115 panics on every start.

The hl-visor that writes the file was published on 9 September 2026. Its size is 8305392 bytes. Visors from before September 2026 are about 5.5 to 6 MB.

3. Check your hl-visor#

# local binary: size and date
ls -l /usr/local/bin/hl-visor

# published binary: size and date
curl -sI https://binaries.hyperliquid.xyz/Mainnet/hl-visor | grep -iE 'last-modified|content-length'

If the published binary is newer or a different size, your visor is out of date. Adjust the path if your systemd unit runs the visor from somewhere else; systemctl cat hl-visor shows it.

4. Fix#

Stop the node first. The supervisor scans running processes at startup and panics when another process carries its binary names in the command line, so download to a neutral filename and keep the service stopped until the new binary is in place. If you run your own watchdog, pause it for the recovery. A watchdog restart interrupts the state download that follows.

sudo systemctl stop hl-visor

# download and verify (key CF2C2EA3DC3E8F042A55FB6503254A9349F1820B, from the node repo's pub_key.asc)
curl -fsS -o /root/visor.new https://binaries.hyperliquid.xyz/Mainnet/hl-visor
curl -fsS -o /root/visor.new.asc https://binaries.hyperliquid.xyz/Mainnet/hl-visor.asc
gpg --verify /root/visor.new.asc /root/visor.new    # must say "Good signature from Hyperliquid"

# keep the old binary, install the new one, start
sudo cp -a /usr/local/bin/hl-visor /usr/local/bin/hl-visor.bak
sudo install -m 0755 /root/visor.new /usr/local/bin/hl-visor
sudo systemctl start hl-visor

gpg also prints a warning that the key is not certified with a trusted signature. That only means you have not signed the key yourself. The fingerprint line must match the key above.

5. Verify the recovery#

• About one minute after start, ~/hl/hyperliquid_data/node_metadata.json exists.
• No new files appear under visor_child_stderr with the panic.
• Within five to ten minutes the journal shows applied block lines again.
• A node that was hours behind first downloads a state snapshot from a peer, then replays at roughly twice chain speed until it reaches the tip.

ls -l ~/hl/hyperliquid_data/node_metadata.json
journalctl -u hl-visor --since "-10min" -o cat | grep -E "applied block" | tail -3

6. After the fix#

Every block the node did not apply is missing from its output files. Fill the gap from Hyperliquid's public S3 archive. A day in this loop is about one million blocks. The historical data guide covers the archive buckets and formats.

Binary 115 also writes a full EVM state checkpoint every 10000 blocks and keeps all of them. Watch the disk in the first day after the upgrade. The checkpoint pruning guide shows the cleanup.

7. Next time#

• Compare your hl-visor with the published one once a day and alert when they differ. The fixed visor was available six weeks before this hardfork.
• Alert on the child's stderr: the same panic in several files in a row is a crash loop, and restarting does not help.
• Watch hyperliquid-dex/node releases and issues. This crash was reported there on the day of the hardfork.

Questions#

Related guides#

• How to run a Hyperliquid non-validator node
• Hyperliquid node disk filling up: EVM checkpoints and how to prune them
• Hyperliquid historical data: API, S3 archive and Python

References#

• hyperliquid-dex/node issue #182. Public report of this crash loop and the hl-visor update that fixes it.
• hyperliquid-dex/node. Download commands, gpg verification and pub_key.asc.
• Hyperliquid docs: Nodes. Official node documentation.
• binaries.hyperliquid.xyz/Mainnet/hl-visor. The published mainnet supervisor binary.