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 and EXPLORER_METAMASK_TECHNICAL_RESPONSE.md.

---

"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:

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 (SSL Certificate Fix), 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):

   # 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 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 — 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.
• 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

# 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