Error Handling Reference
API Errors
Transaction Not Found
Error: Transaction not found
Hash: 0x1234...Causes:
- Transaction not yet mined (pending in mempool)
- Wrong chain selected
- Invalid transaction hash
Solutions:
- Wait and retry - transaction may be pending
- Try other chains:
--chain polygon,--chain arbitrum - Verify hash format (66 characters, starts with 0x)
- Check mempool explorers for pending transactions
Rate Limit Exceeded
Error: Explorer API error: Max rate limit reachedCauses:
- Too many requests in short period
- No API key configured (5/sec limit)
- API key quota exhausted
Solutions:
Wait 1-5 seconds and retry
Add API key for higher limits:
export ETHERSCAN_API_KEY=your_key_hereUse caching to reduce requests
Upgrade to paid API tier
RPC Connection Failed
Error: RPC error: {'code': -32000, 'message': 'execution timeout'}Causes:
- RPC endpoint overloaded
- Network connectivity issues
- Complex query timeout
Solutions:
- Retry with different RPC endpoint
- Check internet connection
- Use dedicated RPC (Alchemy, Chainstack, Infura, or QuickNode)
- Simplify query or add timeout
Invalid Address Format
Error: Invalid address: 0xinvalidCauses:
- Missing or extra characters
- Invalid checksum (mixed case)
- Non-hex characters
Solutions:
- Verify 42 characters (with 0x prefix)
- Use checksummed address from explorer
- Convert to lowercase if checksum fails
Chain-Specific Errors
Wrong Chain
Error: Transaction not foundWhen transaction exists on different chain.
Solutions:
Try common chains in order:
python blockchain_explorer.py tx 0x... --chain ethereum python blockchain_explorer.py tx 0x... --chain polygon python blockchain_explorer.py tx 0x... --chain arbitrumCheck original source for chain info
Use multi-chain search tools
Contract Not Verified
Error: Contract source code not verifiedCauses:
- Contract source not published to explorer
- Proxy contract (implementation elsewhere)
Solutions:
- Use known function signatures database
- Check if proxy - find implementation address
- Decode manually using known ABIs
Token Resolution Errors
Unknown Token
Token: ??? (Unknown Token)Causes:
- New or obscure token
- CoinGecko doesn't track it
- Wrong contract address
Solutions:
- Check token contract on explorer
- Look up on DEX (Uniswap, SushiSwap)
- Manually specify decimals if known
Price Unavailable
Price: N/ACauses:
- Token not on CoinGecko
- API rate limited
- Very low liquidity token
Solutions:
- Check DEX for on-chain price
- Use alternative price feed
- Calculate from LP reserves
Output Errors
Encoding Issues
UnicodeEncodeError: 'ascii' codec can't encode characterSolutions:
- Use
--format jsonfor safe output - Set terminal encoding:
export LANG=en_US.UTF-8 - Pipe to file:
> output.txt
Large Output Truncated
[Output truncated - use --format json for full data]Solutions:
- Use
--format jsonand redirect to file - Reduce
--limitparameter - Process in batches
Environment Setup Errors
Missing Dependencies
ImportError: No module named 'requests'Solutions:
pip install requests
# Or for full setup:
pip install requests web3API Key Not Found
Warning: No API key found for ETHERSCAN_API_KEY
Using free tier (5 req/sec limit)Solutions:
Get free API key from etherscan.io
Set environment variable:
export ETHERSCAN_API_KEY=your_keyAdd to shell profile for persistence
Recovery Strategies
Automatic Retry
The CLI implements exponential backoff:
- 1st retry: 1 second delay
- 2nd retry: 2 second delay
- 3rd retry: 4 second delay
- Max retries: 3
Fallback Chain
When transaction not found, try:
- ethereum
- polygon
- arbitrum
- optimism
- bsc
Cache Recovery
Clear corrupted cache:
rm ~/.blockchain_explorer_cache.jsonDebug Mode
Enable verbose output for troubleshooting:
python blockchain_explorer.py tx 0x... --verboseShows:
- API requests being made
- Response times
- Cache hits/misses
- Rate limit status