proxmox/docs/archive/fixes/BLOCKSCOUT_WEB_INTERFACE_404_FIX.md

Blockscout Web Interface 404 Fix Guide

Date: December 23, 2025
Issue: "Page not found" at https://explorer.d-bis.org/
Status: 🔍 INVESTIGATING

---

🔍 Current Situation

What's Working ✅

• ✅ Blockscout container running
• ✅ PostgreSQL database healthy
• ✅ 115,954 blocks indexed
• ✅ API endpoints responding (with parameters)
• ✅ SSL/HTTPS configured
• ✅ Nginx proxy working
• ✅ Cloudflare tunnel routing correctly

What's Not Working ❌

• ❌ Root path (/) returns "Page not found"
• ❌ /blocks returns 404
• ❌ /transactions returns 404
• ❌ /address/* returns 404

---

🔍 Analysis

Configuration Check

Environment Variables:

• ✅ DISABLE_WEBAPP=false (Webapp enabled)
• ✅ DISABLE_INDEXER=false (Indexer enabled)
• ✅ BLOCKSCOUT_HOST=explorer.d-bis.org
• ✅ BLOCKSCOUT_PROTOCOL=https
• ✅ SECRET_KEY_BASE set

Status: Configuration appears correct.

---

📋 Blockscout API Parameters

Required API Parameters

Blockscout API endpoints require specific parameters:

1. Status Endpoint

GET /api/v2/status?module=block&action=eth_block_number

Parameters:

• module (required): Module name (e.g., block, transaction, account)
• action (required): Action name (e.g., eth_block_number, eth_get_block_by_number)

2. Block Information

GET /api?module=block&action=eth_block_number

Parameters:

• module=block
• action=eth_block_number (or other block actions)

3. Transaction Information

GET /api?module=transaction&action=eth_getTransactionByHash&txhash=<HASH>

Parameters:

• module=transaction
• action=eth_getTransactionByHash
• txhash=<transaction_hash> (required for transaction queries)

---

🔧 Possible Causes of 404 on Root Path

1. Web Interface Not Fully Initialized ⚠️

Cause: Blockscout web interface may need more time to initialize or needs specific data.

Check:

# Check if Phoenix endpoint is running
docker logs blockscout | grep -i phoenix

# Check for web interface startup messages
docker logs blockscout | grep -i "webapp\|web app"

---

2. Missing Static Files ⚠️

Cause: Web interface static files may not be generated.

Check:

docker exec blockscout ls -la /app/apps/explorer/priv/static/

---

3. Route Configuration ⚠️

Cause: Blockscout may need specific route configuration or initialization.

Possible Solutions:

• Check if Blockscout needs a recompilation
• Verify static assets are available
• Check if web interface needs specific environment variables

---

4. Insufficient Indexed Data ⚠️

Current: 115,954 blocks indexed

Note: Even with blocks indexed, the web interface might need:

• At least one transaction indexed
• Address data populated
• Specific data structure in place

---

🔧 Fix Options

Option 1: Verify Web Interface is Enabled

Check current configuration:

docker exec blockscout env | grep DISABLE_WEBAPP

Expected: DISABLE_WEBAPP=false

If set to true, update and restart:

cd /opt/blockscout
sed -i 's/DISABLE_WEBAPP=true/DISABLE_WEBAPP=false/' docker-compose.yml
docker-compose restart blockscout

---

Option 2: Restart Blockscout Container

Sometimes a restart helps initialize the web interface:

cd /opt/blockscout
docker-compose restart blockscout

Wait 2-3 minutes for full initialization.

---

Option 3: Check Static Assets

Verify static files are present:

docker exec blockscout ls -la /app/apps/explorer/priv/static/

If empty or missing, may need to rebuild or reinitialize.

---

Option 4: Access via Direct IP (Test)

Test if web interface works on direct IP:

curl -k https://192.168.11.140/blocks

---

📝 Working Endpoints (What You CAN Access)

API Endpoints (With Parameters)

1. Block Number:

   GET /api?module=block&action=eth_block_number
   

2. Block by Number:

   GET /api?module=block&action=eth_get_block_by_number&tag=<BLOCK_NUMBER>
   

3. Transaction by Hash:

   GET /api?module=transaction&action=eth_getTransactionByHash&txhash=<HASH>
   

4. Address Info:

   GET /api?module=account&action=eth_get_balance&address=<ADDRESS>&tag=latest
   

---

🧪 Testing Commands

Test API Endpoints

# Get latest block number
curl -k "https://explorer.d-bis.org/api?module=block&action=eth_block_number"

# Get block by number
curl -k "https://explorer.d-bis.org/api?module=block&action=eth_get_block_by_number&tag=0x1&boolean=true"

# Get transaction (if you have a transaction hash)
curl -k "https://explorer.d-bis.org/api?module=transaction&action=eth_getTransactionByHash&txhash=<HASH>"

---

💡 Recommendations

Immediate Actions

1. Check Blockscout Logs:

   docker logs -f blockscout | grep -iE "(webapp|phoenix|error|404)"
   

2. Verify Webapp is Running:

   docker exec blockscout ps aux | grep -i phoenix
   

3. Test Direct API Calls:

   curl -k "https://explorer.d-bis.org/api?module=block&action=eth_block_number"
   

Short-Term

1. Wait for More Data:

   • Web interface may need more indexed data
   • Wait 1-2 hours for more blocks/transactions

2. Check Documentation:

   • Review Blockscout documentation for web interface requirements
   • Verify all required environment variables are set

Long-Term

1. Monitor Indexing:

   • Track when web interface becomes available
   • Document the data requirements

2. Document Working Routes:

   • Create a guide of accessible endpoints
   • Document API parameter requirements

---

📚 Blockscout Required Parameters Reference

API Endpoint Format

All Blockscout API calls require:

GET /api?module=<MODULE>&action=<ACTION>[&<PARAMETERS>]

Common Modules and Actions

Module	Actions	Required Parameters
block	eth_block_number, eth_get_block_by_number	tag (for block by number)
transaction	eth_getTransactionByHash	txhash
account	eth_get_balance, txlist	address, tag
token	tokeninfo, tokenbalance	contractaddress, address
stats	ethsupply, ethsupplyexchange	None

Example API Calls

# Get latest block number
curl "https://explorer.d-bis.org/api?module=block&action=eth_block_number"

# Get block 100
curl "https://explorer.d-bis.org/api?module=block&action=eth_get_block_by_number&tag=0x64&boolean=true"

# Get transaction
curl "https://explorer.d-bis.org/api?module=transaction&action=eth_getTransactionByHash&txhash=0x..."

# Get address balance
curl "https://explorer.d-bis.org/api?module=account&action=eth_get_balance&address=0x...&tag=latest"

---

✅ Next Steps

1. Verify Web Interface Status:

   • Check logs for webapp initialization
   • Verify Phoenix endpoint is running

2. Test API Endpoints:

   • Use the API with proper parameters
   • Document working endpoints

3. Monitor Progress:

   • Wait for more data to be indexed
   • Check if web interface becomes available

4. Check Blockscout Documentation:

   • Review requirements for web interface
   • Verify all configuration is correct

---

Status: 🔍 Investigating - Configuration appears correct, checking web interface initialization