Skip to main content

​
Connection Issues

​
HashPilot not appearing in editor

Symptoms: MCP tools not available, server not listed Solutions:
  1. Verify your config file is in the correct location
  2. Check JSON syntax is valid (no trailing commas)
  3. Restart your editor completely
  4. Check if npx hashpilot runs successfully in terminal

​
”Server disconnected” or timeout errors

Solutions:
  1. Check your internet connection
  2. Verify Hedera network is operational at status.hedera.com
  3. Try switching to a different network (testnet → mainnet)

​
Authentication Errors

​
INVALID_ACCOUNT_ID

Cause: Account ID format is incorrect Solution: Use format 0.0.12345 (realm.shard.num)

​
INVALID_SIGNATURE or KEY_PREFIX_MISMATCH

Cause: Private key format is incorrect Solutions:
  1. Ensure key is in hex format (not DER encoded)
  2. Remove any prefixes like “302e020100…”
  3. Use the raw 64-character hex key

​
INSUFFICIENT_PAYER_BALANCE

Cause: Account doesn’t have enough HBAR for transaction fees Solutions:
  1. Check balance: "Check balance of 0.0.12345"
  2. Fund from Hedera Portal (testnet)
  3. Transfer HBAR from another account

​
RAG / Documentation Errors

​
”openaiApiKey is required”

Cause: OpenAI API key not configured Solution: Add OPENAI_API_KEY to your MCP config:

​
Empty search results

Cause: Query too specific or ChromaDB not accessible Solutions:
  1. Try broader search terms
  2. Check if the hosted ChromaDB is accessible
  3. Verify OpenAI API key is valid

​
Token Operations

​
TOKEN_NOT_ASSOCIATED_TO_ACCOUNT

Cause: Account must associate with token before receiving it Solution: Associate first, then transfer:

​
TOKEN_HAS_NO_SUPPLY_KEY

Cause: Trying to mint/burn tokens without supply key Solution: When creating token, include supply key:

​
Smart Contract Issues

​
CONTRACT_REVERT_EXECUTED

Cause: Contract execution failed (reverted) Solutions:
  1. Check function parameters match expected types
  2. Verify account has sufficient balance
  3. Review contract require() conditions
  4. Use error_explain tool for details

​
Gas estimation failed

Solutions:
  1. Increase gas limit manually
  2. Check if function exists in ABI
  3. Verify contract is deployed on target network

​
Network Issues

​
Network not reachable

Solutions:
  1. Check status.hedera.com for outages
  2. Try a different network
  3. Verify your firewall allows HTTPS connections

​
Wrong network

Cause: Operating on wrong network (e.g., mainnet instead of testnet) Solution: Switch network:
Or update config:

​
Common Error Codes

​
Getting Help

If you’re still stuck:
  1. Use error_explain tool:
  2. Check GitHub Issues: github.com/justmert/hashpilot/issues
  3. Hedera Discord: hedera.com/discord
  4. Hedera Documentation: docs.hedera.com