# Troubleshooting
Common issues and solutions for Hyperion MCP Server.
## Installation Issues
### Node.js Version Error
**Problem:**
```
Error: The engine "node" is incompatible with this module
```
**Solution:**
- Check Node.js version: `node --version`
- Upgrade to Node.js v18 or higher
- Use nvm to manage Node versions:
```bash
nvm install 18
nvm use 18
```
### Build Failures
**Problem:**
```
npm run build fails with TypeScript errors
```
**Solution:**
1. Clean and reinstall dependencies:
```bash
rm -rf node_modules package-lock.json
npm install
```
2. Ensure TypeScript is installed:
```bash
npm install -g typescript
```
3. Try building again:
```bash
npm run build
```
### Missing Dependencies
**Problem:**
```
Error: Cannot find module 'ethers'
```
**Solution:**
```bash
npm install
npm run build
```
## Connection Issues
### RPC Connection Failed
**Problem:**
```
Error: Failed to connect to Hyperion RPC
```
**Solutions:**
1. **Check RPC URL:**
```bash
# Test RPC connectivity
curl https://rpc.hyperion-testnet.metisdevops.link
```
2. **Verify Network:**
- Ensure you're using the correct RPC URL
- Check your internet connection
- Try alternative RPC endpoints
3. **Check Firewall:**
- Ensure port 443 is open
- Disable VPN temporarily to test
- Check corporate firewall settings
### Network Timeout
**Problem:**
```
Error: Request timeout after 30000ms
```
**Solutions:**
- Increase timeout in configuration
- Check network stability
- Try during off-peak hours
- Use a different RPC endpoint
## Wallet Issues
### Invalid Private Key
**Problem:**
```
Error: Invalid private key format
```
**Solutions:**
- Ensure private key is 64 hex characters
- Remove '0x' prefix if present
- Check for extra spaces or newlines
- Verify the key is valid hex (0-9, a-f)
**Correct Format:**
```
abc123def456789012345678901234567890123456789012345678901234
```
**Incorrect Formats:**
```
0xabc123... (has 0x prefix)
abc 123... (has space)
```
### Invalid Mnemonic
**Problem:**
```
Error: Invalid mnemonic phrase
```
**Solutions:**
- Ensure mnemonic has 12 or 24 words
- Check spelling of each word
- Verify words are from BIP39 wordlist
- Remove extra spaces between words
### Wallet Not Found
**Problem:**
```
Error: No wallet configured
```
**Solutions:**
1. Create a wallet:
```
Create a new wallet named "my-wallet"
```
2. Or import existing wallet:
```
Import wallet with private key: abc123...
```
3. Set current wallet:
```
Set current wallet to "my-wallet"
```
### Insufficient Balance
**Problem:**
```
Error: Insufficient funds for transaction
```
**Solutions:**
1. Check your balance:
```
Check my tMETIS balance
```
2. Get testnet tokens:
- Visit: https://hyperion-testnet.metisdevops.link/faucet
- Enter your wallet address
- Request tokens
3. Wait for tokens to arrive (1-2 minutes)
## Transaction Issues
### Transaction Failed
**Problem:**
```
Error: Transaction reverted
```
**Common Causes & Solutions:**
1. **Insufficient Gas:**
- Increase gas limit
- Estimate gas first:
```
Estimate gas for sending 1 tMETIS to 0x742d35...
```
2. **Insufficient Balance:**
- Check balance includes gas costs
- Ensure you have enough for amount + gas
3. **Invalid Recipient:**
- Verify recipient address is valid
- Check address checksum
- Ensure address is not a contract (for native transfers)
### Gas Estimation Failed
**Problem:**
```
Error: Cannot estimate gas
```
**Solutions:**
- Check recipient address is valid
- Ensure you have sufficient balance
- Verify contract address (for token transfers)
- Try with manual gas limit:
```
Send 1 tMETIS to 0x742d35... with gas limit 50000
```
### Transaction Stuck/Pending
**Problem:**
Transaction shows as pending for long time
**Solutions:**
1. Check transaction status:
```
Get transaction details for 0xabc123...
```
2. Wait for network confirmation (can take 1-5 minutes)
3. Check gas price was sufficient
4. If truly stuck, try:
- Sending new transaction with higher gas price
- Using same nonce to replace transaction
## Token Issues
### Token Deployment Failed
**Problem:**
```
Error: Contract deployment failed
```
**Solutions:**
1. Check gas limit is sufficient (try 3,000,000)
2. Verify wallet has enough tMETIS for gas
3. Ensure all parameters are valid:
- Name and symbol are non-empty
- Initial supply is positive
- Decimals is 0-18
### Cannot Mint Tokens
**Problem:**
```
Error: Only owner can mint tokens
```
**Solutions:**
- Verify you're using the wallet that deployed the contract
- Check token is mintable
- Ensure you're the contract owner:
```
Get token info for 0xtoken123...
```
### Token Transfer Failed
**Problem:**
```
Error: ERC20 transfer failed
```
**Solutions:**
1. Check token balance:
```
Check balance of token 0xtoken123... for my wallet
```
2. Verify token contract address is correct
3. Ensure recipient address is valid
4. Check you have enough tMETIS for gas
## MCP Integration Issues
### Claude Desktop Not Detecting Server
**Problem:**
Server doesn't appear in Claude Desktop
**Solutions:**
1. Verify configuration file location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Check JSON syntax is valid:
```json
{
"mcpServers": {
"hyperion": {
"command": "node",
"args": ["/absolute/path/to/build/index.js"]
}
}
}
```
3. Use absolute path, not relative
4. Restart Claude Desktop completely
### Cline Can't Find Server
**Problem:**
Cline shows error loading MCP server
**Solutions:**
1. Check path in Cline settings
2. Ensure server is built: `npm run build`
3. Reload VS Code window
4. Check Cline logs for specific errors
### Tools Not Available
**Problem:**
MCP client doesn't show Hyperion tools
**Solutions:**
1. Verify server is running
2. Check server logs for errors
3. Restart MCP client
4. Test server directly:
```bash
node build/index.js
```
## Debugging Tips
### Enable Debug Logging
Add to your `.env` file:
```bash
DEBUG=hyperion:*
LOG_LEVEL=debug
```
### Check Server Logs
Run server directly to see logs:
```bash
node build/index.js
```
### Test Individual Components
Test wallet creation:
```bash
node -e "const {WalletManager} = require('./build/wallet-manager.js'); const wm = new WalletManager(); console.log(wm.createWallet('test'));"
```
### Verify Network Connectivity
Test RPC endpoint:
```bash
curl -X POST https://rpc.hyperion-testnet.metisdevops.link \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```
## Getting Help
If you're still experiencing issues:
1. **Check GitHub Issues:**
- Search existing issues: https://github.com/cuongpo/hyperion-mcp-server/issues
- Create new issue with details
2. **Provide Information:**
- Node.js version
- Operating system
- Error messages (full stack trace)
- Steps to reproduce
3. **Include Logs:**
- Server logs
- MCP client logs
- Transaction hashes (if applicable)
4. **Community Support:**
- Join Discord/Telegram (if available)
- Ask in GitHub Discussions
---
**Next**: Check the [FAQ](./faq.md) for quick answers →
