Troubleshooting

Prerequisites: Quick Start and Configuration.

Is My Gateway Running?

curl http://localhost:48123/metrics | grep gateway_id
docker logs optimum-gateway --tail=10

Gateway Startup Issues

Container Won't Start

lsof -i :33211 -i :33212 -i :43213 -i :48123
python -c "import yaml; yaml.safe_load(open('config/app_conf.yml'))"
docker logs optimum-gateway --timestamps

Causes: Port conflicts, invalid YAML, missing config, wrong volume mount.

Config File Issues

ls -la config/app_conf.yml
docker inspect optimum-gateway | grep -A 5 "Mounts"

Identity Directory Issues

docker exec optimum-gateway ls -la /tmp/libp2p /tmp/mump2p
mkdir -p data/libp2p data/mump2p

Mount identity dirs as volumes to persist across restarts.

Normal Errors (Ignore These)

failed to connect to bootstrap node... i/o timeout
failed to send handshake for peer... connection closed
failed to load topics data... file does not exist

Expected during startup or on first run; does not affect functionality.

Real Connection Issues

Missing gateway_id:

gateway_id: "your_unique_identifier"

Verify gateway is running:

curl -s http://localhost:48123/api/v1/version

CL Client Connection Issues

Verify CL Connection

curl -s http://localhost:48123/metrics | grep -E "cl_peers|libp2p_total_messages"

When CL is connected: optp2p_gateway_optimum_gateway_cl_peers ≥ 1, optp2p_gateway_optimum_gateway_libp2p_total_messages > 0.

Lighthouse Not Reconnecting After Gateway Restart

Lighthouse does not re-dial peers automatically. If the gateway restarts, Lighthouse stays disconnected.

Fix: Add your Lighthouse node as a direct_cl_peer in the gateway config:

direct_cl_peers:
  - /ip4/YOUR_LIGHTHOUSE_IP/tcp/9000/p2p/YOUR_LIGHTHOUSE_PEER_ID

The gateway will run a background goroutine that keeps retrying the connection. See Configuration – Direct CL Peers.

Prysm

curl -s "http://localhost:3500/eth/v1/node/peers" | grep -c "connected"

Fixes: Correct --peer multiaddr; gateway and Prysm reachable on 33212.

Lighthouse v8.x PeerDAS Configuration (Important)

Lighthouse v8.x (post-Fulu/PeerDAS) may disconnect from the gateway. Add:

command:
  - lighthouse
  - beacon_node
  - --network=hoodi
  - --semi-supernode
  - --target-peers=500
  - --libp2p-addresses=/ip4/YOUR_GATEWAY_IP/tcp/33212
  - --trusted-peers=YOUR_GATEWAY_PEER_ID

Why: PeerDAS changes peer requirements; --semi-supernode and --target-peers=500 prevent pruning.

Lighthouse v8.0.0 Release Notes

Getting Peer Information

curl -s http://localhost:48123/api/v1/self_info | jq -r '.peer_id'

Network & Ports

Port	Direction	Usage	Open in firewall
33211	Inbound	Sidecar gRPC (mump2p tracer)	Yes
33212	Inbound	libp2p listener for CL peers	Yes
48123	Inbound	Telemetry API (/metrics, /api/v1/version, /api/v1/self_info)	Yes
43213	Outbound	mump2p egress to Optimum network	No (outbound only)

sudo lsof -i :33211 -i :33212 -i :43213 -i :48123
sudo ufw allow 33211/tcp
sudo ufw allow 33212/tcp
sudo ufw allow 48123/tcp

Only 33211, 33212, and 48123 need UFW allow rules; 43213 is outbound-only.

Docker: Use --network host for simplest setup.

Fork Digest

Fork digest is resolved automatically. Use short topic names only:

eth_topics_subscribe:
  - beacon_block

If topics fail, verify chain matches your network (mainnet vs hoodi).

Telemetry & Monitoring

No data in Grafana:

curl http://localhost:48123/metrics | grep optp2p_gateway

Ensure telemetry_enable: true and Prometheus can reach the gateway.

Quick Commands

docker restart optimum-gateway
docker logs optimum-gateway -f
curl http://localhost:48123/metrics | grep gateway_id