Errors & Troubleshooting¶

Common errors and how to resolve them.

Error Categories¶

Category	Description
`ABIError`	Base error for all ABI-related issues
`ABINotFoundError`	ABI could not be retrieved
`ABIParseError`	ABI JSON structure is invalid
`ABIValidationError`	ABI content is invalid
`NetworkError`	Network/RPC related issues
`GenerationError`	Code generation failed

Fetching Errors¶

Contract source code not verified¶

ABINotFoundError: Contract source code not verified

Cause: The contract is not verified on the block explorer.

Solutions:

Use a local ABI file if you have one:

abi-to-mcp generate ./abi.json -a 0x...

Try Sourcify which may have the contract:

abi-to-mcp generate 0x... --prefer-sourcify

Verify the contract on Etherscan if you're the owner

API rate limit exceeded¶

NetworkError: API rate limit exceeded. Please try again later.

Cause: Too many API requests to the block explorer.

Solutions:

Use an API key:
```
export ETHERSCAN_API_KEY=your-key-here
```
Wait and retry - rate limits usually reset quickly
Use a paid API plan for higher limits

Invalid address format¶

ABIValidationError: Invalid address format: 0x123

Cause: The address is not a valid Ethereum address.

Solutions:

Check address length - must be 42 characters (0x + 40 hex)
Check for typos in the address
Include 0x prefix

Network not found¶

NetworkError: Unknown network: mynetwork

Cause: The specified network is not configured.

Solutions:

Check network name - use --network mainnet, not --network ethereum
See available networks:
```
abi-to-mcp networks list
```
Add custom network - see Custom Networks Guide

Parsing Errors¶

Invalid ABI structure¶

ABIParseError: Invalid ABI: expected array, got object

Cause: The ABI is not a valid JSON array.

Solutions:

Check file format - ABI should be a JSON array:
```
[{"type": "function", ...}, ...]
```
Extract from artifact - Hardhat/Truffle artifacts wrap ABI:
```
abi = artifact["abi"]  # Extract ABI array
```

Unknown type¶

ABIParseError: Unknown Solidity type: myCustomType

Cause: A custom or non-standard type was found.

Solutions:

Check ABI source - may be corrupted or modified

User-defined types are typically tuples in the ABI:

{"name": "param", "type": "tuple", "components": [...]}

Missing required field¶

ABIValidationError: Missing required field 'type' in ABI entry

Cause: An ABI entry is missing required fields.

Solutions:

Validate ABI format using:
```
abi-to-mcp validate ./abi.json
```
Check ABI source - may be truncated or corrupted

Generation Errors¶

Output directory exists¶

GenerationError: Output directory already exists: ./my-server

Cause: The output directory is not empty.

Solutions:

Use --force to overwrite:

abi-to-mcp generate 0x... -o ./my-server --force

Choose different directory:

abi-to-mcp generate 0x... -o ./my-server-v2

Template error¶

GenerationError: Template rendering failed: undefined variable 'xyz'

Cause: Custom template has an error.

Solutions:

Check custom templates for syntax errors
Use default templates by removing custom template config
Check variable names match available context

Runtime Errors¶

Could not connect to RPC¶

NetworkError: Could not connect to RPC: https://...

Cause: The RPC endpoint is unreachable.

Solutions:

Check RPC URL is correct
Check network connectivity
Try a different RPC provider
Check API key if using authenticated endpoint

execution reverted¶

ContractRevertError: execution reverted: ERC20: transfer amount exceeds balance

Cause: The contract function reverted.

Common Causes:

Message	Meaning
`transfer amount exceeds balance`	Not enough tokens
`insufficient allowance`	Need to approve first
`Ownable: caller is not the owner`	Only owner can call
`Pausable: paused`	Contract is paused

Solutions:

Check balances before transferring
Check allowances before transferFrom
Verify permissions for restricted functions
Check contract state (paused, etc.)

Insufficient funds for gas¶

InsufficientFundsError: Insufficient funds for gas * price + value

Cause: Not enough ETH for transaction gas.

Solutions:

Add ETH to your wallet
Reduce gas price (may take longer)
Use simulation to estimate cost first

Nonce too low¶

TransactionError: nonce too low

Cause: Transaction with this nonce already mined.

Solutions:

Wait for pending transactions to confirm

Get current nonce from chain:

nonce = await w3.eth.get_transaction_count(address)

Chain ID mismatch¶

NetworkError: Chain ID mismatch: expected 1, got 137

Cause: Connected to wrong network.

Solutions:

Check RPC URL matches intended network
Check chain ID in configuration

Use correct network flag:

abi-to-mcp generate 0x... -n polygon  # Not mainnet

Troubleshooting Checklist¶

Generation Issues¶

[ ] Is the ABI source valid? (abi-to-mcp validate)
[ ] Is the address correct format?
[ ] Is the network specified correctly?
[ ] Do you have an API key set?
[ ] Is the output directory writable?

Runtime Issues¶

[ ] Is RPC_URL set correctly?
[ ] Is the RPC endpoint accessible?
[ ] Is PRIVATE_KEY set (for writes)?
[ ] Do you have sufficient balance?
[ ] Are you on the correct network?

Contract Issues¶

[ ] Is the contract verified?
[ ] Is the contract address correct?
[ ] Is the contract on this network?
[ ] Is the ABI up to date?

Getting Help¶

If you can't resolve an issue:

Check existing issues: GitHub Issues
Open a new issue with:
Full error message
Command or code used
ABI file (if not from verified contract)
Network and address

Enable debug logging:

export ABI_TO_MCP_LOG_LEVEL=DEBUG
abi-to-mcp generate 0x...