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:

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

Or manually check:

```bash
# 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**:
```bash
# 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**:
```bash
# 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:

```bash
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**:
```bash
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

```bash
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

```bash
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

```bash
pct exec 5000 -- systemctl restart nginx
```

### Step 4: Verify

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

Should return HTTP 200.

---

## Quick Diagnostic Commands

Run these to diagnose the issue:

```bash
# 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`