proxmox/docs/09-troubleshooting/METAMASK_TROUBLESHOOTING_GUIDE.md

# MetaMask Troubleshooting Guide - ChainID 138

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

**Network:** SMOM-DBIS-138 (ChainID 138).

---

## 🔍 Common Issues & Solutions

### 1. Network Connection Issues

#### Issue: "Could not fetch chain ID. Is your RPC URL correct?"

**Symptoms**:
- MetaMask shows error: "Could not fetch chain ID. Is your RPC URL correct?"
- Network won't connect
- Can't fetch balance

**Root Cause**: The RPC endpoint is requiring JWT authentication, which MetaMask doesn't support.

**Solutions**:

1. **Remove and Re-add Network with Correct RPC URL**
   - MetaMask → Settings → Networks
   - Find "Defi Oracle Meta Mainnet" or "SMOM-DBIS-138"
   - Click "Delete" or "Remove"
   - Click "Add Network" → "Add a network manually"
   - Enter these exact values:
     - **Network Name**: `Defi Oracle Meta Mainnet`
     - **RPC URL**: `https://rpc-http-pub.d-bis.org`
     - **Chain ID**: `138` (must be decimal, not hex)
     - **Currency Symbol**: `ETH`
     - **Block Explorer URL**: `https://explorer.d-bis.org` (optional)
   - Click "Save"

2. **If RPC URL Still Requires Authentication (Server Issue)**
   - The public RPC endpoint should NOT require JWT authentication
   - Contact network administrators to fix server configuration
   - VMID 2502 should serve `rpc-http-pub.d-bis.org` WITHOUT authentication
   - Check Nginx configuration on VMID 2502

3. **Verify RPC Endpoint is Working**
   ```bash
   # Test if endpoint responds (should return chain ID 0x8a = 138)
   curl -X POST https://rpc-http-pub.d-bis.org \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
   ```
   - **Expected**: `{"jsonrpc":"2.0","id":1,"result":"0x8a"}`
   - **If you get JWT error**: Server needs to be reconfigured

#### Issue: "Network Error" or "Failed to Connect"

**Symptoms**:
- MetaMask shows "Network Error"
- Can't fetch balance
- Transactions fail immediately

**Solutions**:

1. **Verify RPC URL**
   ```
   Correct: https://rpc-http-pub.d-bis.org
   Incorrect: http://rpc-http-pub.d-bis.org (missing 's')
   Incorrect: https://rpc-core.d-bis.org (deprecated/internal)
   ```

2. **Check Chain ID**
   - Must be exactly `138` (decimal)
   - Not `0x8a` (that's hex, but MetaMask expects decimal in manual entry)
   - Verify in network settings

3. **Remove and Re-add Network**
   - Settings → Networks → Remove the network
   - Add network again with correct settings
   - See [Quick Start Guide](../01-getting-started/METAMASK_QUICK_START_GUIDE.md)

4. **Clear MetaMask Cache**
   - Settings → Advanced → Reset Account (if needed)
   - Or clear browser cache and reload MetaMask

5. **Check RPC Endpoint Status**
   ```bash
   curl -X POST https://rpc-http-pub.d-bis.org \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
   ```

---

### 2. Token Display Issues

#### Issue: "6,000,000,000.0T WETH" Instead of "6 WETH"

**Root Cause**: WETH9 contract's `decimals()` returns 0 instead of 18

**Solution**:

1. **Remove Token**
   - Find WETH9 in token list
   - Click token → "Hide token" or remove

2. **Re-import with Correct Decimals**
   - Import tokens → Custom token
   - Address: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
   - Symbol: `WETH`
   - **Decimals: `18`** ⚠️ **Critical: Must be 18**

3. **Verify Display**
   - Should now show: "6 WETH" or "6.0 WETH"
   - Not: "6,000,000,000.0T WETH"

**See**: 
- [Token Balance Display Incorrect](#2-token-balance-display-incorrect) (this guide) - WETH9 decimals
- [Network Connection Issues](#1-network-connection-issues) (this guide) - RPC Chain ID errors
- [RPC Public Endpoint Routing](../05-network/RPC_PUBLIC_ENDPOINT_ROUTING.md) - Architecture and routing details

---

#### Issue: Token Not Showing Balance

**Symptoms**:
- Token imported but shows 0 balance
- Token doesn't appear in list

**Solutions**:

1. **Check Token Address**
   - WETH9: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
   - WETH10: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
   - Verify address is correct (case-sensitive)

2. **Verify You Have Tokens**
   ```bash
   cast call 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
     "balanceOf(address)" <YOUR_ADDRESS> \
     --rpc-url https://rpc-http-pub.d-bis.org
   ```

3. **Refresh Token List**
   - Click "Import tokens" → Refresh
   - Or remove and re-add token

4. **Check Network**
   - Ensure you're on ChainID 138
   - Tokens are chain-specific

---

### 3. Transaction Issues

#### Issue: Transaction Stuck or Pending Forever

**Symptoms**:
- Transaction shows "Pending" for extended time
- No confirmation after hours

**Solutions**:

1. **Check Network Status**
   - Verify RPC endpoint is responding
   - Check block explorer for recent blocks

2. **Check Gas Price**
   - May need to increase gas price
   - Network may be congested

3. **Replace Transaction** (Same Nonce)
   - Create new transaction with same nonce
   - Higher gas price
   - This cancels the old transaction

4. **Reset Nonce** (Last Resort)
   - Settings → Advanced → Reset Account
   - ⚠️ This clears transaction history

---

#### Issue: "Insufficient Funds for Gas"

**Symptoms**:
- Transaction fails immediately
- Error: "insufficient funds"

**Solutions**:

1. **Check ETH Balance**
   - Need ETH for gas fees
   - Gas costs vary (typically 0.001-0.01 ETH)

2. **Reduce Gas Limit** (If too high)
   - MetaMask may estimate too high
   - Try manual gas limit

3. **Get More ETH**
   - Request from network administrators
   - Bridge from another chain
   - Use faucet (if available)

---

#### Issue: Transaction Reverted

**Symptoms**:
- Transaction confirmed but reverted
- Error in transaction details

**Solutions**:

1. **Check Transaction Details**
   - View on block explorer
   - Look for revert reason

2. **Common Revert Reasons**:
   - Insufficient allowance (for token transfers)
   - Contract logic error
   - Invalid parameters
   - Out of gas (rare, usually fails before)

3. **Verify Contract State**
   - Check if contract is paused
   - Verify you have permissions
   - Check contract requirements

---

### 4. Price Feed Issues

#### Issue: Price Not Updating

**Symptoms**:
- Oracle price seems stale
- Price doesn't change

**Solutions**:

1. **Check Oracle Contract**
   ```bash
   cast call 0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6 \
     "latestRoundData()" \
     --rpc-url https://rpc-http-pub.d-bis.org
   ```

2. **Verify `updatedAt` Timestamp**
   - Should update every 60 seconds
   - If > 5 minutes old, Oracle Publisher may be down

3. **Check Oracle Publisher Service**
   - Service should be running (VMID 3500)
   - Check service logs for errors

4. **Manual Price Query**
   - Use Web3.js or Ethers.js to query directly
   - See [Quick Start - Reading Price Feeds](../01-getting-started/METAMASK_QUICK_START_GUIDE.md#-reading-price-feeds)

---

#### Issue: Price Returns Zero or Error

**Symptoms**:
- `latestRoundData()` returns 0
- Contract call fails

**Solutions**:

1. **Verify Contract Address**
   - Oracle Proxy: `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6`
   - Ensure correct address

2. **Check Contract Deployment**
   - Verify contract exists on ChainID 138
   - Check block explorer

3. **Verify Network**
   - Must be on ChainID 138
   - Price feeds are chain-specific

---

### 5. Network Switching Issues

#### Issue: Can't Switch to ChainID 138

**Symptoms**:
- Network doesn't appear in list
- Switch fails

**Solutions**:

1. **Add Network Manually**
   - See [Quick Start Guide](../01-getting-started/METAMASK_QUICK_START_GUIDE.md)
   - Ensure all fields are correct

2. **Programmatic Addition** (For dApps)
   ```javascript
   try {
     await window.ethereum.request({
       method: 'wallet_switchEthereumChain',
       params: [{ chainId: '0x8a' }], // 138 in hex
     });
   } catch (switchError) {
     // Network doesn't exist, add it
     if (switchError.code === 4902) {
       await window.ethereum.request({
         method: 'wallet_addEthereumChain',
         params: [networkConfig],
       });
     }
   }
   ```

3. **Clear Network Cache**
   - Remove network
   - Re-add with correct settings

---

### 6. Account Issues

#### Issue: Wrong Account Connected

**Symptoms**:
- Different address than expected
- Can't see expected balance

**Solutions**:

1. **Switch Account in MetaMask**
   - Click account icon
   - Select correct account

2. **Import Account** (If needed)
   - Settings → Import Account
   - Use private key or seed phrase

3. **Verify Address**
   - Check address matches expected
   - Addresses are case-insensitive but verify format

---

#### Issue: Account Not Showing Balance

**Symptoms**:
- Account connected but balance is 0
- Expected to have ETH/tokens

**Solutions**:

1. **Verify Network**
   - Must be on ChainID 138
   - Balances are chain-specific

2. **Check Address**
   - Verify correct address
   - Check on block explorer

3. **Refresh Balance**
   - Click refresh icon in MetaMask
   - Or switch networks and switch back

---

### 7. Swap & Bridge (In-Wallet) — and Send

#### Issue: "No XChain Swaps native asset found for chainId: eip155:138"

**Symptoms**:
- Error when clicking **Send** or opening MetaMask’s in-wallet **Swap** while connected to Chain 138
- Full message: `Error: No XChain Swaps native asset found for chainId: eip155:138` (stack may reference `LavaPack.loadBundle.s.getNativeAssetForChainId`)

**Root Cause**: MetaMask’s LavaPack/XChain logic supports only a fixed list of chains (Ethereum, BNB, Polygon, etc.). Chain 138 is **not** in that list. In some versions the **Send** flow uses the same code (e.g. for gas or asset lookup), so the error can appear when you click **Send**, not only Swap.



**What this error is NOT**:
- **Not about eth_sendTransaction vs eth_sendRawTransaction** — The error is thrown in the extension UI when MetaMask builds or displays the Send screen (inside getNativeAssetForChainId), before any RPC call. Both RPC methods are valid; the failure is in the wallet's native-asset lookup, not in how the tx is submitted.
- **Not caused by your Snap or allowlisting** — The Chain 138 Snap runs in an isolated worker and does not participate in MetaMask's native Send/Swap UI. The extension does not ask Snaps for native asset; it uses LavaPack's internal list. So the error is not due to the Snap having had errors or being allowlisted.


**If it happens when you click Send**:

1. **Use the Chain 138 Snap "Send" page (recommended)** — The Chain 138 Snap companion site has a **Send** page (path `/send`) that sends via the dApp transaction path, so the XChain error does not occur. Open the Snap site, go to **Send on Chain 138**, enter recipient and amount, and click Send; MetaMask will show the normal confirmation. Deploy the companion site (e.g. with the Snap) and share the Send URL with users.
2. **Send from another dApp** — Use any site/dApp that supports Chain 138 and has a "Transfer" or "Send" action; the dApp asks MetaMask to sign, which uses a different path and can succeed.
3. **Try a different Send entry** — In MetaMask, try starting the send from the account/asset view (e.g. click the token or balance and choose Send) instead of the main "Send" button, in case a different code path is used.
4. **Use another wallet** — Add Chain 138 in a wallet that supports custom EVM networks (e.g. via [Chainlist](https://chainlist.org/chain/138)) and does not rely on this backend for Send.

**If it happens on Swap**: Do not use the in-wallet Swap for Chain 138; use a DEX that supports Chain 138.

**References**:
- [MetaMask Bridge & Swap Support for ChainID 138](../../smom-dbis-138/docs/operations/integrations/METAMASK_BRIDGE_SWAP.md) — full status and workarounds
- [MetaMask Chain 138 Feature Parity Analysis](../04-configuration/metamask/METAMASK_CHAIN138_FEATURE_PARITY_ANALYSIS.md)

---

## 🔧 Advanced Troubleshooting

### Enable Debug Mode

**MetaMask Settings**:
1. Settings → Advanced
2. Enable "Show Hex Data"
3. Enable "Enhanced Gas Fee UI"
4. Check browser console for errors

### Check Browser Console

**Open Console**:
- Chrome/Edge: F12 → Console
- Firefox: F12 → Console
- Safari: Cmd+Option+I → Console

**Look For**:
- RPC errors
- Network errors
- JavaScript errors
- MetaMask-specific errors

### Verify RPC Response

**Test RPC Endpoint**:
```bash
curl -X POST https://rpc-http-pub.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'
```

**Expected Response**:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x..."
}
```

---

## 📞 Getting Help

### Resources

1. **Documentation**:
   - [Quick Start Guide](../01-getting-started/METAMASK_QUICK_START_GUIDE.md)
   - [Contract Addresses Reference](../11-references/CONTRACT_ADDRESSES_REFERENCE.md)

2. **Block Explorer**:
   - `https://explorer.d-bis.org`
   - Check transactions, contracts, addresses

3. **Network Status**:
   - RPC: `https://rpc-http-pub.d-bis.org` (public, no auth required)
   - Permissioned RPC: `https://rpc-http-prv.d-bis.org` (requires JWT auth)
   - Verify endpoint is responding

### Information to Provide When Reporting Issues

1. **MetaMask Version**: Settings → About
2. **Browser**: Chrome/Firefox/Safari + version
3. **Network**: ChainID 138
4. **Error Message**: Exact error text
5. **Steps to Reproduce**: What you did before error
6. **Console Errors**: Any JavaScript errors
7. **Transaction Hash**: If transaction-related

---

## ✅ Quick Diagnostic Checklist

Run through this checklist when troubleshooting:

- [ ] Network is "Defi Oracle Meta Mainnet" or "SMOM-DBIS-138" (ChainID 138)
- [ ] RPC URL is `https://rpc-http-pub.d-bis.org` (public endpoint, no auth)
- [ ] Chain ID is `138` (decimal, not hex)
- [ ] RPC endpoint does NOT require JWT authentication
- [ ] Account is connected and correct
- [ ] Sufficient ETH for gas fees
- [ ] Token decimals are correct (18 for WETH)
- [ ] Browser console shows no errors
- [ ] RPC endpoint is responding
- [ ] Block explorer shows recent blocks

---

**Last Updated**: $(date)