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.

**ApiError 400 on dashboard load (already logged in)**

If you see repeated **ApiError code 400** in the console as soon as the NPMplus UI loads (e.g. "Welcome to NPMplus", "You are logged in as Administrator"), the frontend is calling one or more API endpoints that return 400. Common causes:

1. **Find the failing request:** In the browser, open **Developer Tools** → **Network** tab → reload the NPMplus page. Filter by "Fetch/XHR". Find any request with status **400** and note the **Request URL** and **Response** body. Typical endpoints the dashboard calls: `/api/nginx/proxy-hosts`, `/api/nginx/certificates`, `/api/nginx/access-lists`, `/api/settings`, etc.
2. **Test the API from the command line** (from a host that can reach NPMplus):
   ```bash
   # From project root, with NPM_PASSWORD and NPM_EMAIL in .env
   NPM_URL="https://192.168.11.167:81" bash scripts/verify/export-npmplus-config.sh
   ```
   If the export script succeeds, the same GET endpoints work from curl; the 400 may be limited to a specific endpoint or to the browser (e.g. session, or a different endpoint the UI calls). If the script fails with 400, note which step fails (login vs proxy-hosts vs certificates).
3. **Browser:** Try an **incognito/private** window or another browser; clear cache and log in again.
4. **Backend data:** Sometimes one proxy host or certificate record has invalid or unexpected data and the API returns 400 when returning the list. Check NPMplus container logs (see above). If you have a recent backup, you can compare or restore.

See also: [NPMPLUS_UI_APIERROR_400_RUNBOOK.md](NPMPLUS_UI_APIERROR_400_RUNBOOK.md) for a short runbook and API test commands.

---

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