Troubleshooting

Common issues and solutions for RMCP installation, configuration, and usage.

Installation Issues

Python Version Compatibility

Issue: RMCP requires Python 3.11+

Solution:

# Check Python version
python --version

# Install Python 3.11+ if needed
# macOS with Homebrew:
brew install python@3.11

# Ubuntu/Debian:
sudo apt update && sudo apt install python3.11

# Windows: Download from python.org

Package Installation Failures

Issue: pip install rmcp fails

Solutions:

# Upgrade pip first
pip install --upgrade pip

# Try with user flag
pip install --user rmcp

# Use uv (recommended)
pip install uv
uv pip install rmcp

R Integration Issues

R Not Found

Issue: “R not found” or R script errors

Solution: Use Docker for guaranteed R environment:

docker build -f docker/Dockerfile --target development -t rmcp-dev .
docker run -v $(pwd):/workspace -it rmcp-dev bash

R Package Missing

Issue: R statistical tools fail due to missing packages

Solution: RMCP manages R packages automatically through the security whitelist. If you see package errors:

  1. Check available packages: rmcp list-r-packages

  2. The missing package may require approval

  3. Use Docker for complete package environment

Configuration Issues

Port Already in Use

Issue: “Port 8000 already in use” for HTTP server

Solutions:

# Use different port
rmcp serve-http --port 8080

# Or via environment variable
export RMCP_HTTP_PORT=8080
rmcp serve-http

# Find and kill process using port
lsof -ti:8000 | xargs kill

Permission Denied

Issue: Cannot write files or create directories

Solutions:

# Check current directory permissions
ls -la

# Create config directory if missing
mkdir -p ~/.rmcp

# Fix permissions
chmod 755 ~/.rmcp

Runtime Issues

Tool Call Failures

Issue: Statistical tools return errors

Common causes and solutions:

  1. Data format issues:

    # Ensure data is properly formatted
# CSV: comma-separated with headers
# Array: [[1,2], [3,4]] format

  2. Missing required parameters:

    # Check tool schema
rmcp list-capabilities --tool linear_model

  3. R script errors: Check error message for specific R issues

Memory Issues

Issue: “Out of memory” or slow performance

Solutions:

# Increase R memory limit
export RMCP_R_MEMORY_LIMIT=4GB

# Use configuration file
echo '{"r": {"memory_limit": "4GB"}}' > ~/.rmcp/config.json

# For large datasets, consider data sampling

Timeout Issues

Issue: “Timeout waiting for R process”

Solutions:

# Increase timeout
export RMCP_R_TIMEOUT=300

# Via configuration
echo '{"r": {"timeout": 300}}' > ~/.rmcp/config.json

HTTP Server Issues

CORS Errors

Issue: Browser blocks requests due to CORS

Solution:

# Allow all origins (development only)
export RMCP_CORS_ORIGINS="*"

# Production: specify allowed origins
export RMCP_CORS_ORIGINS="https://yourdomain.com,https://app.yourdomain.com"

Session Issues

Issue: “Session not found” or session expires

Solution:

  • Sessions auto-expire after inactivity

  • Re-initialize with initialize method

  • Check session ID in response headers

Claude Desktop Integration

MCP Connection Issues

Issue: Claude Desktop doesn’t find RMCP

Common solutions:

  1. Check Claude Desktop config:

    {
  "mcpServers": {
    "rmcp": {
      "command": "rmcp",
      "args": ["start"]
    }
  }
}

  2. Verify RMCP is in PATH:

    which rmcp
rmcp --version

  3. Use full path:

    {
  "mcpServers": {
    "rmcp": {
      "command": "/full/path/to/rmcp",
      "args": ["start"]
    }
  }
}

Tool Discovery Issues

Issue: Claude Desktop shows “No tools available”

Solutions:

  1. Check RMCP logs: rmcp start --debug

  2. Verify tool registration: rmcp list-capabilities

  3. Restart Claude Desktop after configuration changes

Data Issues

File Reading Errors

Issue: Cannot read CSV/Excel files

Solutions:

# Check file permissions
ls -la yourfile.csv

# Verify file format
head yourfile.csv

# Use absolute paths
rmcp read-csv /full/path/to/file.csv

# Check encoding (especially for international data)
file -I yourfile.csv

Large Dataset Issues

Issue: Performance problems with large datasets

Solutions:

  1. Sample data: Use representative subset

  2. Chunked processing: Process data in smaller pieces

  3. Optimize queries: Filter data before analysis

  4. Use Docker: Better resource management

Debugging

Enable Debug Mode

# CLI debug mode
rmcp start --debug

# Environment variable
export RMCP_LOG_LEVEL=DEBUG
rmcp start

# Configuration file
echo '{"debug": true, "logging": {"level": "DEBUG"}}' > ~/.rmcp/config.json

Check Logs

# View recent logs
tail -f ~/.rmcp/logs/rmcp.log

# Check system logs (Linux)
journalctl -u rmcp

# Docker logs
docker logs <container-id>

Validate Configuration

# Check configuration loading
rmcp config show

# Validate config file
rmcp config validate ~/.rmcp/config.json

# Test connectivity
rmcp health-check

Getting Help

Check System Status

# Overall system check
rmcp diagnose

# List capabilities
rmcp list-capabilities

# Test specific tool
rmcp test-tool linear_model

# Check R integration
rmcp check-r

Common Error Messages

“Module not found: rmcp”

  • RMCP not installed: pip install rmcp

  • Wrong Python environment: Check virtual environment

“R script execution failed”

  • Check R installation with Docker approach

  • Verify data format matches expected schema

“Connection refused”

  • HTTP server not running: rmcp serve-http

  • Wrong port/host configuration

“Permission denied”

  • File permissions issue: Check file/directory access

  • Config directory: Create ~/.rmcp/ if missing

Still Need Help?