proxmox/docs/04-configuration/FIX_502_ERROR_GUIDE.md

Fix 502 Bad Gateway Error - Complete Guide

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Date: 2026-01-18
Status: ⚠️ Action Required

---

Current Situation

The explorer is showing 502 Bad Gateway errors because:

1. NPMplus is still routing to port 80 (nginx on VMID 5000)
2. Nginx cannot reach Blockscout on port 4000 (Blockscout may not be running or not accessible)

---

Solution Options

Option 1: Direct Route (Recommended)

Configure Blockscout to be network-accessible on port 4000, then update NPMplus to route directly to it.

Steps:

1. Fix Blockscout network access (see below)
2. Update NPMplus configuration (see below)

Benefits:

• Removes nginx proxy layer
• Lower latency
• Simpler architecture

Option 2: Fix Nginx Proxy (Alternative)

If Blockscout cannot be made network-accessible, fix the nginx configuration on VMID 5000 to properly proxy to Blockscout.

Steps:

1. Check Blockscout service is running
2. Verify Blockscout is listening on localhost:4000
3. Fix nginx configuration if needed

---

Option 1: Direct Route - Implementation

Step 1: Fix Blockscout Network Access

From Proxmox host, run:

cd /home/intlc/projects/proxmox
./scripts/fix-blockscout-network-access.sh

Or manually check:

# Check Blockscout status
pct exec 5000 -- systemctl status blockscout.service

# Check port listening
pct exec 5000 -- ss -tlnp | grep :4000

# Test localhost access
pct exec 5000 -- curl -I http://127.0.0.1:4000/api/v2/stats

If Blockscout is only on localhost (127.0.0.1:4000):

For Docker containers:

# Check docker-compose.yml or port bindings
pct exec 5000 -- docker ps --format '{{.Names}} {{.Ports}}' | grep blockscout

# Check container configuration
pct exec 5000 -- docker inspect <blockscout-container> | grep -i port

# Update docker-compose.yml to bind to 0.0.0.0:4000:4000 (not 127.0.0.1:4000:4000)
# Restart container

For systemd services:

# Check service file
pct exec 5000 -- systemctl cat blockscout.service

# Update environment variables to bind to 0.0.0.0:4000
# Restart service
pct exec 5000 -- systemctl restart blockscout.service

Step 2: Verify Network Access

From any machine on the network:

curl -I http://192.168.11.140:4000/api/v2/stats

Should return HTTP 200.

Step 3: Update NPMplus

Via Web UI:

1. Log into NPMplus: https://192.168.0.166:81
2. Find explorer.d-bis.org proxy host
3. Update Forward Port: 80 → 4000
4. Save changes
5. Wait 30 seconds for reload

Or use script:

cd /home/intlc/projects/proxmox
./scripts/apply-direct-blockscout-route.sh

---

Option 2: Fix Nginx Proxy - Implementation

If direct route is not possible, fix nginx on VMID 5000:

Step 1: Check Blockscout is Running

pct exec 5000 -- systemctl status blockscout.service
pct exec 5000 -- curl -I http://127.0.0.1:4000/api/v2/stats

Step 2: Check Nginx Configuration

pct exec 5000 -- nginx -t
pct exec 5000 -- cat /etc/nginx/sites-enabled/blockscout

Ensure nginx is configured to proxy to http://127.0.0.1:4000.

Step 3: Restart Nginx

pct exec 5000 -- systemctl restart nginx

Step 4: Verify

curl -I https://explorer.d-bis.org/api/v2/stats

Should return HTTP 200.

---

Quick Diagnostic Commands

Run these to diagnose the issue:

# Check Blockscout service
pct exec 5000 -- systemctl status blockscout.service

# Check port 4000
pct exec 5000 -- ss -tlnp | grep :4000

# Test localhost
pct exec 5000 -- curl -I http://127.0.0.1:4000/api/v2/stats

# Test network (from Proxmox host)
curl -I http://192.168.11.140:4000/api/v2/stats

# Check nginx
pct exec 5000 -- systemctl status nginx
pct exec 5000 -- nginx -t

# Test current route (via NPMplus)
curl -I https://explorer.d-bis.org/api/v2/stats

---

Status Summary

Current State:

• ❌ Blockscout not accessible on port 4000 from network
• ❌ NPMplus still routing to port 80
• ❌ Getting 502 errors

Required Actions:

1. ✅ Fix Blockscout network access (port 4000)
2. ✅ Update NPMplus configuration (port 80 → 4000)

After Fix:

• ✅ Blockscout accessible on port 4000
• ✅ NPMplus routing directly to port 4000
• ✅ No more 502 errors

---

Related Scripts

• scripts/fix-blockscout-network-access.sh - Fix Blockscout network access
• scripts/verify-blockscout-port-4000.sh - Verify port 4000 accessibility
• scripts/apply-direct-blockscout-route.sh - Apply NPMplus update
• scripts/diagnose-explorer-502-error.sh - Comprehensive diagnostics

---

Next Steps

1. Run diagnostic: ./scripts/fix-blockscout-network-access.sh
2. Fix Blockscout: Configure it to listen on 0.0.0.0:4000
3. Verify network access: curl -I http://192.168.11.140:4000/api/v2/stats
4. Update NPMplus: Change port from 80 to 4000
5. Test: curl -I https://explorer.d-bis.org/api/v2/stats