Troubleshooting Guide

Common issues and their solutions when using the ActivityPub MCP Server. Find quick fixes for the most frequent problems.

🔧 Connection Issues

Server Not Responding

Symptoms:

  • Tools timeout or return no response
  • Error: "Failed to connect to MCP server"
  • Claude reports server is unavailable

Solutions:

  1. Check server status: 
    npm run status
  2. Restart the server: 
    npm run restart
  3. Verify configuration: 
    npm run config:check
  4. Check logs for errors: 
    npm run logs

Network Connectivity Problems

Symptoms:

  • Error: "Network request failed"
  • Timeouts when fetching from instances
  • Intermittent connection issues

Solutions:

  1. Check internet connection
  2. Test instance accessibility: 
    curl -I https://mastodon.social
  3. Configure proxy if needed: 
    export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080
  4. Increase timeout settings in config

🚫 Access and Permission Issues

Actor Not Found

Symptoms:

  • Error: "Actor not found"
  • Error: "Failed to resolve actor"
  • Empty results when searching for known actors

Solutions:

  1. Verify actor format: 
    # Correct formats:
@username@instance.com
https://instance.com/users/username
https://instance.com/@username
  2. Check if actor exists: 
    curl https://instance.com/.well-known/webfinger?resource=acct:username@instance.com
  3. Try alternative discovery methods
  4. Clear cache and retry: 
    clear-cache actors

Rate Limiting

Symptoms:

  • Error: "Rate limit exceeded"
  • HTTP 429 responses
  • Requests being throttled

Solutions:

  1. Wait before retrying (usually 15 minutes)
  2. Reduce request frequency
  3. Use different instances to distribute load
  4. Check rate limit headers: 
    curl -I https://instance.com/api/v1/accounts/lookup

Private Content Access

Symptoms:

  • Error: "Access denied"
  • Empty timelines for known active accounts
  • Missing posts or limited content

Solutions:

  1. Respect privacy settings - this is expected behavior
  2. Try public instances and accounts
  3. Use accounts with public timelines
  4. Check instance privacy policies

⚙️ Configuration Issues

Invalid Configuration

Symptoms:

  • Server fails to start
  • Error: "Invalid configuration"
  • Missing required settings

Solutions:

  1. Validate configuration file: 
    npm run config:validate
  2. Reset to default configuration: 
    npm run config:reset
  3. Check required environment variables
  4. Review configuration documentation

Claude Desktop Integration

Symptoms:

  • Tools not appearing in Claude
  • Error: "MCP server not found"
  • Connection refused errors

Solutions:

  1. Check Claude Desktop configuration: 
    # macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows  
%APPDATA%\Claude\claude_desktop_config.json
  2. Verify server path in config
  3. Restart Claude Desktop
  4. Check server logs for connection attempts

📊 Performance Issues

Slow Response Times

Symptoms:

  • Tools take a long time to respond
  • Timeouts on large requests
  • High memory usage

Solutions:

  1. Clear cache: 
    clear-cache all
  2. Reduce request size (limit results)
  3. Use more specific queries
  4. Monitor system resources

Memory Issues

Symptoms:

  • Server crashes with out-of-memory errors
  • Gradual performance degradation
  • High memory usage

Solutions:

  1. Restart server regularly
  2. Reduce cache size in configuration
  3. Limit concurrent requests
  4. Monitor memory usage

🔍 Debugging Tips

Enable Verbose Logging

export DEBUG=activitypub-mcp:*
npm start

This will show detailed logs for all operations.

Test Individual Components

# Test WebFinger resolution
curl "https://instance.com/.well-known/webfinger?resource=acct:user@instance.com"

# Test ActivityPub endpoint
curl -H "Accept: application/activity+json" "https://instance.com/users/username"

Check Instance Health

# Check if instance is up
curl -I https://instance.com

# Check API availability  
curl https://instance.com/api/v1/instance

Monitor Network Traffic

Use browser developer tools or network monitoring tools to see actual HTTP requests and responses.

🆘 Getting Help

📋 Before Reporting Issues

  • Check this troubleshooting guide
  • Review the basic usage guide
  • Test with known working instances (mastodon.social)
  • Collect relevant logs and error messages
  • Note your environment (OS, Node.js version, etc.)

🐛 Reporting Bugs

If you've found a bug, please report it on GitHub:

Report an Issue

Include:

  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Error messages and logs
  • System information

💬 Community Support

Join the discussion for help and tips:

GitHub Discussions

🔗 Related Resources

Basic Usage Guide

Learn the fundamental concepts and workflows.

Practical Examples

See real-world examples and use cases.

Complete Tool Reference

Detailed documentation for all available tools.