Troubleshooting¶

Common issues and their solutions.

Connection Issues¶

RPC Connection Failed¶

Symptoms:

Error: Could not connect to RPC endpoint

Solutions:

1. Check URL format

   # Correct
   ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
   
   # Wrong - missing https
   ETHEREUM_RPC_URL=eth-mainnet.g.alchemy.com/v2/YOUR_KEY
   

2. Test connectivity

   curl -X POST -H "Content-Type: application/json" \
     --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
     $ETHEREUM_RPC_URL
   

3. Check API key

4. Verify key is valid
5. Check rate limits
6. Ensure key has required permissions

Solana Connection Issues¶

Symptoms:

Error: Failed to connect to Solana

Solutions:

1. Use correct network URL

   # Devnet
   SOLANA_RPC_URL=https://api.devnet.solana.com
   
   # Mainnet
   SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
   

2. Check Solana network status

   curl https://api.devnet.solana.com -X POST -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'
   

Deployment Issues¶

Deployment Timeout¶

Symptoms:

TimeoutError: Transaction not confirmed within 120000ms

Solutions:

1. Increase gas price

   switchboard deploy --gas-multiplier 1.5
   

2. Check network congestion

3. Use gas tracker for target network

4. Deploy during low-traffic periods

5. Increase timeout

   // switchboard.config.js
   module.exports = {
     deployment: {
       timeout: 300000, // 5 minutes
     },
   };
   

Insufficient Funds¶

Symptoms:

Error: Insufficient funds for gas

Solutions:

1. Check balance

   switchboard balance --network ethereum
   

2. Get test tokens

   switchboard faucet --network sepolia --address YOUR_ADDRESS
   

3. Estimate fees first

   switchboard estimate --contract MyContract --networks ethereum,polygon
   

Contract Verification Failed¶

Symptoms:

Error: Contract verification failed

Solutions:

1. Check constructor arguments
2. Arguments must match exactly

3. Use correct encoding

4. Verify compiler version

   // hardhat.config.js
   module.exports = {
     solidity: "0.8.19", // Match deployed version
   };
   

5. Retry verification

   switchboard verify --contract MyContract --network ethereum --force
   

Authentication Issues¶

Invalid JWT Token¶

Symptoms:

Error: JWT token expired or invalid

Solutions:

1. Refresh token

   switchboard auth refresh
   

2. Re-login

   switchboard login
   

API Key Not Working¶

Symptoms:

Error: Invalid API key

Solutions:

1. Check key format

   # Correct header
   X-API-Key: cs_live_abc123...
   
   # Wrong - using Bearer
   Authorization: Bearer cs_live_abc123...
   

2. Verify key permissions

3. Check key has required scopes
4. Verify key isn't revoked

Database Issues¶

Connection Refused¶

Symptoms:

Error: ECONNREFUSED 127.0.0.1:27017

Solutions:

1. Check if database is running

   docker-compose ps mongodb
   

2. Start database

   docker-compose up -d mongodb
   

3. Check connection URL

   MONGODB_URL=mongodb://localhost:27017/switchboard
   

Authentication Failed¶

Symptoms:

Error: Authentication failed

Solutions:

1. Check credentials

   MONGODB_URL=mongodb://user:password@localhost:27017/switchboard?authSource=admin
   

2. Reset password

   docker-compose exec mongodb mongosh --eval "db.changeUserPassword('switchboard', 'newpassword')"
   

Performance Issues¶

High Latency¶

Symptoms: - Coordination latency > 400ms - Slow API responses

Solutions:

1. Check network latency

   ping api.devnet.solana.com
   

2. Use closer RPC endpoints

3. Choose geographically close providers

4. Use paid tier for lower latency

5. Enable caching

   REDIS_URL=redis://localhost:6379
   

Memory Issues¶

Symptoms:

Error: JavaScript heap out of memory

Solutions:

1. Increase Node.js memory

   NODE_OPTIONS=--max-old-space-size=4096 npm run dev
   

2. Check for memory leaks

3. Review event listeners
4. Check for unbounded caches

Docker Issues¶

Container Won't Start¶

Solutions:

1. Check logs

   docker-compose logs customer-api
   

2. Verify ports

   lsof -i :3000
   

3. Rebuild containers

   docker-compose down
   docker-compose up -d --build
   

Volume Permission Errors¶

Solutions:

# Fix permissions
sudo chown -R 1000:1000 ./data

# Or run as root (not recommended for production)
docker-compose up -d --user root

Getting More Help¶

If these solutions don't work:

1. Enable debug logging

   DEBUG=switchboard:* switchboard deploy
   

2. Collect diagnostics

   switchboard doctor > diagnostics.txt
   

3. Open an issue with:

4. Error message
5. Steps to reproduce
6. Diagnostics file
7. Environment details