Troubleshooting

npm install fails

Problem: Installation errors or missing dependencies

Solution:

# Clear npm cache
npm cache clean --force

# Update npm
npm install -g npm@latest

# Try installing again
npm install -g mucch

Permission denied on global install

Problem: EACCES error when installing globally

Solution:

# Option 1: Use sudo (macOS/Linux)
sudo npm install -g mucch

# Option 2: Use npx instead (no global install)
npx mucch

# Option 3: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Node version incompatibility

Problem: Errors about unsupported Node.js version

Solution:

# Check your Node version
node --version

# Should be v18.0.0 or higher
# Install nvm to manage Node versions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Invalid API keys

Problem: "Invalid API key" or authentication errors

Solution:

• Verify your .env file exists and is in the correct location
• Check that API keys don't have extra spaces or line breaks
• Ensure OpenAI/OpenRouter keys are valid and have sufficient credits
• Confirm Hyperliquid private key is the correct format (0x...)

# Verify .env file location
ls -la .env

# Check file contents (redacted)
cat .env | grep -v "KEY="

.env file not found

Problem: Bot can't find configuration file

Solution:

# Create .env file from example
cp .env.example .env

# Edit with your values
nano .env

Make sure the .env file is in the same directory where you run the bot.

Invalid asset configuration

Problem: Bot fails to start with asset errors

Solution:

• Verify asset symbols are correct (e.g., BTC not BTCUSD)
• Check that assets are supported on Hyperliquid
• Use comma-separated list: BTC,ETH
• No spaces in the asset list

Garbled display or missing boxes

Problem: Dashboard doesn't render correctly

Solution:

• Use a terminal that supports UTF-8 and 256 colors
• Increase terminal size to at least 120x30 characters
• Try a different terminal emulator (Windows Terminal, iTerm2)
• Set TERM=xterm-256color environment variable

Charts not updating

Problem: Price charts show old or static data

Solution:

• Check internet connection
• Verify Hyperliquid API is accessible
• Press 'r' to manually refresh data
• Restart the bot if problem persists

Dashboard freezes or hangs

Problem: Terminal becomes unresponsive

Solution:

• Press Ctrl+C to force quit
• Check system resources (CPU, memory)
• Reduce number of monitored assets
• Increase check interval in config

AI analysis timeout

Problem: AI requests taking too long or timing out

Solution:

• Check OpenAI/OpenRouter API status
• Verify API key has sufficient credits
• Try switching to alternate provider
• Reduce max_tokens in AI configuration
• Check network latency to API endpoints

AI returns invalid JSON

Problem: Cannot parse AI response

Solution:

• Confirm you're using GPT-5 or Claude 4.5 Sonnet
• Check temperature is set to 0.3 (not higher)
• Verify response_format is set to "json_object" for OpenAI
• Bot will retry automatically up to 3 times

Hyperliquid connection failed

Problem: Cannot connect to Hyperliquid

Solution:

• Check if Hyperliquid is experiencing downtime
• Verify your private key is correct
• If using testnet, set HYPERLIQUID_TESTNET=true
• Check firewall isn't blocking API requests
• Try curl to test connectivity: curl https://api.hyperliquid.xyz/info

Insufficient balance errors

Problem: Cannot place trades due to insufficient funds

Solution:

• Deposit more USDC to your Hyperliquid account
• Reduce RISK_PERCENTAGE (try 0.5% instead of 1%)
• Decrease MAX_POSITIONS to avoid over-allocation
• Close existing positions to free up margin

High CPU or memory usage

Problem: Bot consuming too many resources

Solution:

• Increase CHECK_INTERVAL to 600000 (10 min) or higher
• Monitor fewer assets (2-3 instead of 10+)
• Run without dashboard (use logs only)
• Close unnecessary browser tabs and applications

Slow AI responses

Problem: AI analysis takes more than 30 seconds

Solution:

• Reduce max_tokens from 500 to 300
• Switch AI provider (OpenAI usually faster than Claude)
• Use GPT-5 instead of Claude 4.5 Sonnet for speed
• Check API provider status page