augments

Troubleshooting

Comprehensive troubleshooting guide for the Augments MCP Server including common issues, debugging techniques, and performance optimization.

Quick Diagnostic Checklist
Start here to identify the most common issues quickly

Basic Connectivity

  • MCP server is running and accessible
  • Framework registry loaded successfully
  • GitHub API connectivity (if using GitHub token)
  • Cache directory writable and accessible

Configuration Validation

  • Environment variables set correctly
  • Framework JSON files valid and accessible
  • No validation errors in server logs
  • Claude Desktop MCP configuration correct
Framework Not Found
HIGH
Framework appears in configuration but is not discoverable via MCP tools

Symptoms

  • • Framework missing from list_available_frameworks results
  • • get_framework_info returns 'framework not found' error
  • • Framework search returns no results for known framework

Solutions

  • • Check framework JSON file exists in correct directory (frameworks/category/name.json)
  • • Validate JSON syntax and required fields presence
  • • Verify framework name uses only alphanumeric characters, hyphens, underscores
  • • Check server logs for validation errors during framework loading
  • • Restart server or wait for hot-reload to process changes
Framework Validation Errors
MEDIUM
Framework configuration fails validation during loading

Symptoms

  • • Framework not appearing in available frameworks list
  • • Validation error messages in server logs
  • • Hot-reload not updating framework after changes

Solutions

  • • Check all required fields: name, display_name, category, type, sources, context_files, key_features, common_patterns
  • • Ensure category is one of: web, backend, mobile, ai-ml, design, tools, database
  • • Verify GitHub repository URLs are accessible and correct
  • • Test framework configuration against schema validation
  • • Review server logs for specific validation failure details
Framework Documentation Not Loading
MEDIUM
Framework is found but documentation retrieval fails

Symptoms

  • • Empty or incomplete documentation responses
  • • Timeout errors when accessing framework docs
  • • Documentation source access failures

Solutions

  • • Verify GitHub repository URLs and branch names are correct
  • • Check if repository is public and accessible
  • • Test GitHub token validity and permissions
  • • Verify documentation path exists in repository
  • • Try alternative source (website) if GitHub source fails
  • • Check network connectivity to documentation sources
Debugging Tools & Techniques
Advanced debugging methods for diagnosing complex issues

Server Logging

Enable Debug Logging

# Set environment variable for detailed logging
export AUGMENTS_LOG_LEVEL="DEBUG"

# Or modify server configuration
structlog.configure(
    wrapper_class=structlog.make_filtering_bound_logger(10),  # DEBUG level
    ...
)

Log Analysis Commands

# Monitor real-time logs
tail -f /path/to/server/logs

# Search for specific errors
grep -i "error\|exception\|failed" server.log

# Filter by framework name
grep "framework=nextjs" server.log

# Monitor rate limiting
grep "rate.limit" server.log

MCP Tool Diagnostics

Cache Statistics

# Get comprehensive cache statistics
get_cache_stats

# Expected response includes:
# - memory_entries: Number of entries in memory cache
# - disk_entries: Number of entries on disk
# - cache_directory: Current cache location
# - hit_rate: Cache effectiveness ratio

Registry Information

# Get framework registry statistics
get_registry_stats

# Test specific framework loading
get_framework_info framework_name

# Verify framework availability
list_available_frameworks
search_frameworks "framework_name"

Performance Profiling

Response Time Analysis

# Time framework information requests
time curl -X POST "localhost:3000/mcp" -d '{
  "method": "get_framework_info",
  "params": {"framework": "nextjs"}
}'

# Monitor network latency
ping github.com
curl -w "%{time_total}" -s -o /dev/null https://api.github.com

Resource Usage Monitoring

# Monitor server process resources
ps aux | grep augments-mcp-server
top -p $(pgrep -f augments-mcp-server)

# Check cache directory size
du -sh ~/.cache/augments-mcp-server/

# Monitor file descriptor usage
lsof -p $(pgrep -f augments-mcp-server)
Getting Additional Help
Resources for when standard troubleshooting doesn't resolve the issue

Before Reporting Issues

  • • Collect server logs with debug level enabled
  • • Document reproduction steps clearly
  • • Include environment details (OS, Python version)
  • • Test with minimal configuration to isolate the issue
  • • Check if issue affects specific frameworks or is global

Useful Information to Include

  • • Cache statistics and registry stats output
  • • Network connectivity test results
  • • Framework configuration files (if relevant)
  • • Claude Desktop MCP configuration
  • • Error messages and stack traces