Glimx Troubleshooting Guide

This guide covers common issues you might encounter when using Glimx CLI and how to resolve them.

Installation Issues

Permission Denied During Installation

Problem: You receive a permission denied error when installing Glimx.

Solution:

# Try with sudo for system-wide installation
sudo npm install -g glimx

# Or install to a user directory
npm install -g glimx --prefix ~/.local

Command Not Found

Problem: After installation, the glimx command is not found.

Solution:

# Check if the binary is in your PATH
which glimx

# If not found, add the installation directory to your PATH
export PATH="$PATH:/usr/local/bin"

# For npm global installs, check the npm global bin directory
npm bin -g
export PATH="$PATH:$(npm bin -g)"

Dependency Installation Failures

Problem: Errors occur when installing dependencies during source build.

Solution:

# Clear npm cache
npm cache clean --force

# Remove node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall dependencies
npm install

# If using Bun
bun install --force

Configuration Issues

Invalid Configuration File

Problem: Glimx fails to start with configuration errors.

Solution:

1. Check the error message for specific issues
2. Validate your JSON syntax
3. Ensure all keys are valid according to the schema
4. Use the JSON schema for validation:

{
  "$schema": "https://codelabs-poliwangi.github.io/glimx-cli/config.json"
  // Your configuration
}

Model Not Found

Problem: Error message "Model not found" when starting Glimx.

Solution:

1. Verify your model configuration:

{
  "model": "groq/qwen-32b" // Ensure correct format: provider/model
}

2. Check available models:

• Groq Models
• OpenRouter Models

API Key Issues

Problem: "API key not found" or "Invalid API key" errors.

Solution:

# Verify keys are set
echo $GROQ_API_KEY
echo $OPENROUTER_API_KEY

# Set keys in your environment
export GROQ_API_KEY="your-key-here"
export OPENROUTER_API_KEY="your-key-here"

# Add to shell profile for persistence
echo 'export GROQ_API_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc

Permission Issues

Permission Denied on File Operations

Problem: Glimx asks for permission on every file operation.

Solution:

1. Check your permission configuration:

{
  "permission": {
    "bash": {
      "ls *": "allow", // Allow common safe commands
      "cat *": "allow",
      "*": "ask" // Ask for everything else
    }
  }
}

Git Operations Blocked

Problem: Git operations are blocked or require constant approval.

Solution:

{
  "permission": {
    "bash": {
      "git status": "allow",
      "git diff": "allow",
      "git log": "allow",
      "git add *": "ask",
      "git commit *": "ask",
      "git push *": "ask",
      "*": "ask"
    }
  }
}

MCP Server Issues

MCP Server Not Starting

Problem: MCP servers fail to start or are not available.

Solution:

1. Check if required dependencies are installed:

# For filesystem server
npx -y @modelcontextprotocol/server-filesystem --help

# For git server
uvx mcp-server-git --help

2. Verify MCP configuration:

{
  "mcp": {
    "filesystem": {
      "enabled": true,
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "~"]
    }
  }
}

MCP Server Timeout

Problem: MCP servers time out during operations.

Solution:

1. Increase timeout values:

{
  "mcp": {
    "slow-server": {
      "type": "local",
      "command": ["slow-mcp-server"],
      "enabled": true,
      "timeout": 30000 // Increase to 30 seconds
    }
  }
}

2. Check server responsiveness:

# Test the server command directly
npx -y @modelcontextprotocol/server-filesystem ~

Performance Issues

Slow Startup

Problem: Glimx takes a long time to start.

Solution:

1. Disable unused MCP servers:

{
  "mcp": {
    "unused-server": {
      "enabled": false
    }
  }
}

2. Check for network issues with remote MCP servers

High Memory Usage

Problem: Glimx consumes excessive memory.

Solution:

1. Limit session history:

glimx --compact // Use compact mode to reduce memory

2. Restart Glimx periodically to clear memory

Model-related Issues

Rate Limiting

Problem: "Rate limit exceeded" errors from AI providers.

Solution:

1. Check provider rate limits:

• Groq: 1000 requests/day
• OpenRouter: 20 req/min, 50 req/day
• Cerebras: 30 req/min

2. Use different models or providers:

glimx --model openrouter/deepseek-chat

Model Not Responding

Problem: Model appears to hang or not respond.

Solution:

1. Try a different model:

glimx --model groq/llama-3.3-70b

2. Check your internet connection

3. Verify API keys are valid

Terminal and UI Issues

Display Problems

Problem: Garbled text or display issues in terminal.

Solution:

1. Check terminal compatibility:

# Ensure you're using a modern terminal
echo $TERM

2. Try a different theme:

{
  "theme": "default" // Try default theme
}

Keybind Conflicts

Problem: Keybinds not working or conflicting with terminal.

Solution:

1. Customize keybinds:

{
  "keybinds": {
    "leader": "ctrl+space", // Change leader key
    "app_exit": "ctrl+c,ctrl+d,<leader>q"
  }
}

Network Issues

Connection Timeouts

Problem: Network timeouts when connecting to AI providers.

Solution:

1. Check internet connectivity:

ping google.com

2. Increase timeout settings:

{
  "provider": {
    "groq": {
      "options": {
        "timeout": 60000 // 60 seconds
      }
    }
  }
}

Proxy Issues

Problem: Behind a corporate proxy that blocks connections.

Solution:

1. Configure proxy settings:

export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

2. Configure in provider options:

{
  "provider": {
    "groq": {
      "options": {
        "baseURL": "http://proxy.company.com:8080/https://api.groq.com/openai/v1"
      }
    }
  }
}

Development Issues

Build Failures

Problem: Errors when building from source.

Solution:

1. Ensure you have the correct Node.js/Bun version:

node --version # Should be v18+
bun --version # Should be v1.0+

2. Clean and rebuild:

cd glimx-cli
git clean -xfd
bun install
cd packages/opencode
bun run build

Type Errors

Problem: TypeScript errors during development.

Solution:

1. Run type checking:

bun run typecheck

2. Fix reported errors or update dependencies

Logging and Debugging

Enable Debug Logging

To get more detailed information about what Glimx is doing:

# Set debug level
export OPENCODE_LOG_LEVEL=debug

# Run Glimx
glimx

View Logs

Glimx logs are stored in:

• macOS/Linux: ~/.opencode/logs/
• Windows: %USERPROFILE%\.opencode\logs\

# View recent logs
tail -f ~/.opencode/logs/glimx.log

Updating Issues

Update Failures

Problem: Unable to update Glimx.

Solution:

1. Update via package manager:

npm update -g glimx
# or
bun update -g glimx

2. If built from source:

cd glimx-cli
git pull
bun install
cd packages/opencode
bun run build

Getting Help

If you're still experiencing issues:

1. Check GitHub Issues: https://github.com/codelabs-poliwangi/glimx-cli/issues
2. Create a New Issue: Include:
   • Glimx version (glimx --version)
   • Operating system and version
   • Error messages
   • Steps to reproduce
3. Contact Support: codelabs@poliwangi.ac.id

Contributing Fixes

If you've resolved an issue that others might face:

1. Fork the repository
2. Create a branch with your fix
3. Add documentation to this troubleshooting guide
4. Submit a pull request

Version Compatibility

Ensure you're using compatible versions:

Component	Minimum Version	Recommended Version
Node.js	18.0.0	20.0.0+
Bun	1.0.0	1.1.0+
Git	2.0.0	2.40.0+

Keep your tools updated for the best experience with Glimx.