Configuration Troubleshooting

This section helps diagnose and fix common configuration issues.

Configuration Not Loading

Check File Permissions

Configuration files must be readable by the RMCP process:

# Check file permissions
ls -la ~/.rmcp/config.json
ls -la /etc/rmcp/config.json

# Fix permissions if needed
chmod 644 ~/.rmcp/config.json
sudo chmod 644 /etc/rmcp/config.json

Verify JSON Syntax

Configuration files must be valid JSON:

# Validate JSON syntax
python -m json.tool ~/.rmcp/config.json

# Or use jq if available
jq . ~/.rmcp/config.json

Check Environment Variables

List all RMCP environment variables:

# List RMCP environment variables
env | grep RMCP_

# Check specific variable
echo $RMCP_HTTP_PORT

Enable Debug Mode

Use debug mode to see configuration loading details:

# Command line debug
rmcp --debug start

# Environment variable
export RMCP_DEBUG=true
rmcp start

# Config file debug
echo '{"debug": true}' > ~/.rmcp/config.json
rmcp start

Invalid Configuration Values

Port Number Issues

Ports must be between 1-65535:

# Invalid port (will fail)
export RMCP_HTTP_PORT=70000

# Valid port
export RMCP_HTTP_PORT=8080

Timeout Configuration

Timeouts must be positive integers:

{
  "r": {
    "timeout": 180,         // Valid: positive integer
    "session_timeout": 3600 // Valid: positive integer
  }
}

File Size Limits

File sizes must be positive integers (bytes):

{
  "security": {
    "vfs_max_file_size": 52428800  // Valid: 50MB in bytes
  }
}

Log Level Validation

Log levels must be valid Python logging levels:

# Valid log levels
export RMCP_LOG_LEVEL=DEBUG
export RMCP_LOG_LEVEL=INFO
export RMCP_LOG_LEVEL=WARNING
export RMCP_LOG_LEVEL=ERROR
export RMCP_LOG_LEVEL=CRITICAL

# Invalid log level (will fail)
export RMCP_LOG_LEVEL=VERBOSE

Environment Variable Issues

Variable Naming

Environment variables must use the RMCP_ prefix and exact names:

# Correct
export RMCP_HTTP_HOST=0.0.0.0
export RMCP_HTTP_PORT=8000

# Incorrect (will be ignored)
export HTTP_HOST=0.0.0.0
export RMCP_HOST=0.0.0.0

List Values

Use commas to separate list items:

# Correct: comma-separated values
export RMCP_HTTP_CORS_ORIGINS="https://app1.com,https://app2.com"
export RMCP_VFS_ALLOWED_PATHS="/data,/tmp,/home/user"

# Incorrect: spaces will not work
export RMCP_HTTP_CORS_ORIGINS="https://app1.com https://app2.com"

Boolean Values

Use standard boolean representations:

# Valid boolean values
export RMCP_DEBUG=true
export RMCP_DEBUG=false
export RMCP_DEBUG=1
export RMCP_DEBUG=0
export RMCP_DEBUG=yes
export RMCP_DEBUG=no
export RMCP_DEBUG=on
export RMCP_DEBUG=off

SSL Configuration Issues

Missing SSL Files

Both SSL key and certificate files must be provided:

{
  "http": {
    "ssl_keyfile": "/etc/ssl/private/rmcp.key",    // Both required
    "ssl_certfile": "/etc/ssl/certs/rmcp.crt"      // Both required
  }
}

File Path Validation

SSL files must exist and be readable:

# Check SSL files exist
ls -la /etc/ssl/private/rmcp.key
ls -la /etc/ssl/certs/rmcp.crt

# Check permissions
sudo chmod 600 /etc/ssl/private/rmcp.key
sudo chmod 644 /etc/ssl/certs/rmcp.crt

R Configuration Issues

R Binary Not Found

If R is not in PATH, specify the full path:

{
  "r": {
    "binary_path": "/usr/local/bin/R"
  }
}

Session Limits

Ensure session limits match available memory:

{
  "r": {
    "max_sessions": 10,     // ~1-2GB memory required
    "session_timeout": 3600 // Clean up idle sessions
  }
}

Security Configuration Issues

VFS Path Access

Ensure allowed paths exist and are accessible:

# Check path exists
ls -la /data/allowed/path

# Check permissions
chmod 755 /data/allowed/path

Read-Only Mode

In production, keep VFS in read-only mode:

{
  "security": {
    "vfs_read_only": true,  // Recommended for production
    "vfs_allowed_paths": ["/data/readonly"]
  }
}

Configuration Debugging Commands

Complete Diagnostic

Run these commands to diagnose configuration issues:

# 1. Check configuration file syntax
python -m json.tool ~/.rmcp/config.json

# 2. List environment variables
env | grep RMCP_ | sort

# 3. Test configuration loading
rmcp --debug start --dry-run

# 4. Check file permissions
ls -la ~/.rmcp/config.json /etc/rmcp/config.json

# 5. Validate paths exist
ls -la /path/to/ssl/files

Configuration Validation

Enable verbose validation output:

# Show configuration loading details
RMCP_DEBUG=true rmcp start

# Show final resolved configuration
rmcp config show

# Validate configuration without starting
rmcp config validate

Common Error Messages

“HTTP port must be between 1-65535”

Fix: Set a valid port number:

export RMCP_HTTP_PORT=8000

“SSL key file is required when SSL certificate is specified”

Fix: Provide both SSL files:

export RMCP_HTTP_SSL_KEYFILE=/path/to/key.pem
export RMCP_HTTP_SSL_CERTFILE=/path/to/cert.pem

“Configuration file not found”

Fix: Create configuration file or specify correct path:

# Create default config directory
mkdir -p ~/.rmcp

# Use custom config file
rmcp --config /path/to/config.json start

“Log level must be one of {DEBUG, INFO, WARNING, ERROR, CRITICAL}”

Fix: Use a valid log level:

export RMCP_LOG_LEVEL=INFO