proxmox/docs/04-configuration/EXPLORER_TROUBLESHOOTING.md

# Explorer Troubleshooting Guide

**Last Updated:** 2026-02-06  
**Document Version:** 1.0  
**Status:** Active Documentation

---

**Last updated:** 2026-02-06

**Reference screenshots:** For expected explorer UI (home, blocks, transactions), see [../images/README.md](../images/README.md) and [EXPLORER_METAMASK_TECHNICAL_RESPONSE.md](EXPLORER_METAMASK_TECHNICAL_RESPONSE.md#3-explorer-backend-stack).

---

## "Your connection isn't private" / net::ERR_CERT_AUTHORITY_INVALID

**Symptom:** Browser shows "Your connection isn't private" or "Attackers might be trying to steal your information" for `https://explorer.d-bis.org` with **net::ERR_CERT_AUTHORITY_INVALID**.

**Cause:** The site is served with a **self-signed or invalid certificate**. NPMplus (the reverse proxy for explorer.d-bis.org) must present a trusted certificate (e.g. Let's Encrypt).

**Quick checklist:** (1) Open NPMplus at **https://192.168.11.167:81** (use .167 if .166 refuses; credentials in `.env`: `NPM_EMAIL`, `NPM_PASSWORD`). (2) SSL Certificates → Add Let's Encrypt for `explorer.d-bis.org` (DNS Challenge + Cloudflare credential if needed). (3) Proxy Hosts → explorer.d-bis.org → SSL tab → assign that cert, Force SSL, Save. (4) Reload https://explorer.d-bis.org. If you get ApiError 400, see the subsection below.

**Fix (recommended): Request Let's Encrypt in NPMplus**

**Option A – One command via SSH to Proxmox host (so NPMplus at .166/.167 is reachable)**  
If `explorer.d-bis.org` has **no** certificate assigned in NPMplus, you can request and assign one by running on the LAN host:

```bash
cd /path/to/proxmox
bash scripts/run-via-proxmox-ssh.sh request-cert --host 192.168.11.11
```

That copies the script and `.env` to r630-01 and runs `request-npmplus-certificates.sh` (FIRST_ONLY=1) there, so the NPM API at 192.168.11.167:81 is reachable. If the explorer host already has a (self-signed) cert assigned, the script skips it (Successful: 0) — use Option B to add a Let's Encrypt cert in the UI and assign it to the proxy host.

**Option B – Manual in NPMplus UI**

1. From a machine on the same LAN, open **NPMplus**: `https://192.168.11.167:81` (or `https://192.168.11.166:81` if .166 works; credentials: `NPM_EMAIL`, `NPM_PASSWORD` from `.env`). If one refuses connection, try the other.
2. **SSL Certificates** → **Add SSL Certificate** → **Let's Encrypt**.
3. **Domain Names:** `explorer.d-bis.org`  
   **Email:** your email (e.g. `NPM_EMAIL` from `.env`)  
   **I Agree to the Let's Encrypt Terms:** ✓  
   **Save**.
4. **Proxy Hosts** → open the **explorer.d-bis.org** proxy host → **SSL** tab.
5. **SSL Certificate:** select the Let's Encrypt cert you just added.  
   Enable **Force SSL**, **HTTP/2 Support**, and optionally **HSTS**.  
   **Save**.
6. Wait 1–2 minutes for issuance. Reload `https://explorer.d-bis.org` in the browser (hard refresh or new incognito window).

**Requirements for Let's Encrypt:** `explorer.d-bis.org` must resolve to the same public IP that receives HTTPS (e.g. 76.53.10.36). Port 80 must be reachable from the internet for the ACME HTTP-01 challenge (or use DNS challenge if your NPMplus/ACME client supports it).

**Temporary workaround (testing only):** In some browsers you can click **Advanced** → **Proceed to explorer.d-bis.org (unsafe)**. If the site sends **HSTS**, the browser may not offer "Proceed" — in that case the only fix is to install a valid certificate (Option A or B above).

**More detail:** [explorer-monorepo/EXTERNAL_ACCESS_WORKING.md](../../../explorer-monorepo/EXTERNAL_ACCESS_WORKING.md) (SSL Certificate Fix), [explorer-monorepo/NPMPLUS_CREDENTIALS_GUIDE.md](../../../explorer-monorepo/NPMPLUS_CREDENTIALS_GUIDE.md).

### NPMplus "ApiError" code 400 (empty message)

If the NPMplus UI shows **ApiError** with **code: 400** and an empty or vague message when you add an SSL certificate or save a proxy host:

- **Adding a Let's Encrypt certificate**
  - **Domain:** Use exactly one domain per certificate (e.g. `explorer.d-bis.org`) with no spaces or leading/trailing dots.
  - **Email:** Fill in a valid email; some NPM versions require it.
  - **I agree to the Let's Encrypt Terms:** Must be checked.
  - **DNS Challenge + Cloudflare:** If you chose DNS Challenge, you must have a **Cloudflare credential** saved in NPMplus (SSL Certificates → Add → use "Credentials File Content" with `dns_cloudflare_api_token = YOUR_TOKEN` or `dns_cloudflare_email` + `dns_cloudflare_api_key`). If the credential is missing or wrong, the backend can return 400. Create the credential first under the certificate form or in a separate step, then request the cert again.
  - **HTTP-01:** If you use HTTP Challenge, port **80** must be reachable from the internet for the domain (and the domain must resolve to that IP). If it isn’t, try DNS Challenge with a valid Cloudflare credential instead.
- **Saving a proxy host**
  - 400 can happen if the UI sends a field the API rejects. Try changing only the SSL tab (certificate + Force SSL) and save; if it still returns 400, try another browser or clear cache and log in again.

If 400 persists, check the NPMplus container logs (e.g. from the Proxmox host: `pct exec 10233 -- tail -100 /data/logs/*.log` or the path your NPMplus uses) for the actual validation or backend error.

---

## Fixes Applied (2026-01-31)

### 1. Duplicate nginx configs removed
- **Issue:** Three config files in `sites-enabled` (blockscout, blockscout.backup, blockscout.bak) caused "conflicting server name" warnings.
- **Fix:** Moved backup files to `sites-available/backups/`. Only `blockscout` remains active.

### 2. RPC URLs updated for mobile/public access
- **Issue:** Explorer used internal IPs (`192.168.11.250`) for RPC — unreachable from mobile/cellular and VMID 2500 was destroyed.
- **Fix:** Replaced with public URLs:
  - `RPC_URL`: `https://rpc-http-pub.d-bis.org`
  - `RPC_WS_URL`: `wss://rpc-ws-pub.d-bis.org`
- **CSP** `connect-src` updated to allow public RPC endpoints.

### 3. Favicon 404
- Added nginx `location = /favicon.ico` to proxy to Blockscout (reduces 404 log noise).

---

## If Explorer Still Fails

### On same LAN (Wi‑Fi at home/office)

**Symptom:** Works on mobile cellular but not on Wi‑Fi, or vice versa.

**Possible cause: NAT hairpin / loopback**

When on your LAN, `explorer.d-bis.org` resolves to `76.53.10.36`. If that’s your UDM’s WAN IP, the UDM must “hairpin” (forward traffic to itself) to NPMplus. Some routers don’t support this well.

**Fix: Split-horizon DNS**

1. **UniFi Network** → **Settings** → **DNS** (or **Local DNS** / **Network**)
2. Add a **Local DNS Record** (or equivalent):
   - **Domain:** `explorer.d-bis.org`
   - **IP:** `192.168.11.167` (NPMplus)
3. LAN clients will resolve `explorer.d-bis.org` to NPMplus directly — no hairpin needed.

### On mobile cellular

1. **Clear browser cache** (or use incognito/private mode)
2. **Check DNS:** Settings → Wi‑Fi or cellular → DNS → use `1.1.1.1` or `1.0.0.1`
3. **Test API:** Open `https://explorer.d-bis.org/api/v2/stats` — if it loads, the site is reachable and the issue may be with the main page or JS.

### Page loads but features fail

- **RPC errors:** Ensure you’re using the updated explorer with public RPC URLs (see above).
- **MetaMask / wallet:** Use the `/wallet` page to add Chain 138.
- **Blocks not updating:** Check Blockscout logs:  
  `ssh root@192.168.11.12 "pct exec 5000 -- docker logs blockscout --tail 50"`

### "Invalid address" when clicking From/To in transaction list

**Symptom:** Clicking the **From** or **To** cell in the transactions table (especially when **To** shows "—" for contract-creation txs) shows an "Invalid address" toast or error.

**Cause:** Those cells were clickable even when the value was empty or "N/A", so the app tried to open an address detail for an invalid value.

**Fix (applied in explorer SPA):** From/To cells are now only clickable when the value is a valid `0x` address. Clicking "—" or "N/A" no longer triggers the address detail; the row still opens the transaction detail when you click elsewhere on the row.

### Contract verification fails (502 / Invalid JSON)

When running `run-contract-verification-with-proxy.sh` or Forge verify, you may see "Blockscout returned HTML" or 502. This usually means Blockscout (VMID 5000) is down or the DB needs migrations.

- **Fix Blockscout:** [03-deployment/BLOCKSCOUT_FIX_RUNBOOK.md](../03-deployment/BLOCKSCOUT_FIX_RUNBOOK.md) — SSL/migrations, thin pool, start stack.
- **Verify from UI:** When https://explorer.d-bis.org is up, use **Address → Contract → Verify & Publish** (no proxy needed). See [08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md).
- **From LAN:** Run verification script from a host that can reach `http://192.168.11.140:4000` so the proxy can forward to Blockscout.

---

## Verify Explorer

```bash
# Homepage
curl -sI https://explorer.d-bis.org/

# Wallet
curl -sI https://explorer.d-bis.org/wallet

# Config API
curl -s https://explorer.d-bis.org/api/config/networks | head -5

# Stats
curl -s https://explorer.d-bis.org/api/v2/stats | head -5
```

---

## Architecture

```
User → DNS (1.1.1.1) → explorer.d-bis.org = 76.53.10.36
     → UDM Pro :443 → 192.168.11.167 (NPMplus)
     → NPMplus proxy host explorer.d-bis.org → 192.168.11.140:80
     → VMID 5000 nginx → / → index.html, /api/* → Blockscout/APIs
```