Troubleshooting

​

Connection Issues

​

HashPilot not appearing in editor

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

# Test if HashPilot runs
npx hashpilot

​

”Server disconnected” or timeout errors

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

"HEDERA_OPERATOR_ID": "0.0.12345"  // Correct
"HEDERA_OPERATOR_ID": "12345"      // Wrong

​

INVALID_SIGNATURE or KEY_PREFIX_MISMATCH

• DER-encoded hex (starts with 302e... or 3030...): the curve is encoded in the key, nothing else to configure.
• Raw 64-character hex (with or without 0x): the bytes do not say which curve they belong to. HashPilot assumes ECDSA, which is what the Hedera Portal issues by default. For an ED25519 account, set HEDERA_OPERATOR_KEY_TYPE=ed25519.

// Either of these works
"HEDERA_OPERATOR_KEY": "302e020100300506032b657004220420abc123..."   // DER
"HEDERA_OPERATOR_KEY": "abc123def456..."                                // raw hex, ECDSA assumed

// Raw hex for an ED25519 account
"HEDERA_OPERATOR_KEY": "abc123def456...",
"HEDERA_OPERATOR_KEY_TYPE": "ed25519"

​

INSUFFICIENT_PAYER_BALANCE

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”

"env": {
  "OPENAI_API_KEY": "sk-proj-..."
}

​

Empty search results

1. Try broader search terms
2. Ask for health_check with verbose: true; the services.chromadb entry shows the index URL and whether its heartbeat succeeded
3. Verify OpenAI API key is valid
4. If you set CHROMA_URL, check that your own server is running and indexed (see Self-hosting)

​

Token Operations

​

TOKEN_NOT_ASSOCIATED_TO_ACCOUNT

"Associate token 0.0.12345 with account 0.0.67890"
"Transfer 100 tokens to account 0.0.67890"

​

TOKEN_HAS_NO_SUPPLY_KEY

"Create token with supply key enabled"

​

Smart Contract Issues

​

CONTRACT_REVERT_EXECUTED

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

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

​

Verification fails or previewnet cannot be verified

1. Verify on testnet or mainnet; previewnet contracts cannot be verified
2. Pass the exact source file and contract name to verify_contract
3. For Hardhat projects ask for hardhat_contract verify; it locates the build-info file and lists the npx hardhat verify and verify.sourcify.dev alternatives
4. For Foundry run forge verify-contract --verifier sourcify --chain 296 <address> src/Contract.sol:Contract

​

”forge: command not found” or Hardhat errors on init

1. Install Foundry with foundryup (HashPilot also looks in ~/.foundry/bin)
2. Check that npm is on the PATH of the process that launched your editor
3. Pass an absolute directory for every project operation

​

Network Issues

​

Network not reachable

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

​

Wrong network

"Switch to testnet network"

"HEDERA_NETWORK": "testnet"

​

Common Error Codes

​

Getting Help

1. Read the Best Practices for keys, networks, providers and costs
2. Use error_explain tool:
   "Explain error INSUFFICIENT_PAYER_BALANCE"
   
3. Check GitHub Issues: github.com/justmert/hashpilot/issues
4. Hedera Discord: hedera.com/discord
5. Hedera Documentation: docs.hedera.com