Troubleshooting Guide

This guide covers common issues and their solutions for the Plugged.in platform. Use this as a reference when encountering problems.

Quick Diagnostics

Health Check Commands

# Check if services are running
systemctl status pluggedin-app pluggedin-mcp

# Check logs for errors
journalctl -u pluggedin-app -f
tail -f /var/log/pluggedin/app.log

# Test database connectivity
pnpm db:check

# Verify MCP proxy health
curl http://localhost:12005/health

Common Status Codes

200: Success
400: Bad Request - Check your parameters
401: Unauthorized - Check API key
403: Forbidden - Insufficient permissions
404: Not Found - Check endpoint URL
429: Rate Limited - Too many requests
500: Server Error - Check server logs

MCP Server Issues

”Session not found” Errors

Symptoms:

MCP tools return “Session not found”
Server appears offline in web interface

Solutions:

Check MCP Proxy Status

# Verify proxy is running
systemctl status pluggedin-mcp

# Check proxy logs
journalctl -u pluggedin-mcp -n 50

Restart MCP Proxy

# Restart the proxy service
systemctl restart pluggedin-mcp

# Or manually restart
cd pluggedin-mcp && pnpm start

Clear Browser Cache

# Hard refresh in browser
Ctrl+Shift+R (Linux/Windows)
Cmd+Shift+R (Mac)

Tool Name Collisions

Symptoms:

Tools from different servers have same names
Some tools not appearing in client

Solutions:

Enable UUID Prefixing (v2.9.0+)

# Check if UUID prefixing is enabled
grep UUID_PREFIX pluggedin-app/.env

# Enable if not set
echo "UUID_PREFIX_ENABLED=true" >> pluggedin-app/.env

Manual Server Restart

# Restart app to apply changes
pm2 restart pluggedin-app

Sandboxing Issues

Symptoms:

STDIO servers fail to start
Permission denied errors
Sandbox-related failures

Solutions:

Check Sandbox Configuration

# Verify sandbox settings
grep MCP_ISOLATION pluggedin-app/.env

# Required settings
echo "MCP_ISOLATION_TYPE=bubblewrap" >> pluggedin-app/.env
echo "MCP_ISOLATION_FALLBACK=firejail" >> pluggedin-app/.env

Install Dependencies

# Ubuntu/Debian
sudo apt-get install bubblewrap firejail fuse3

# CentOS/RHEL
sudo yum install bubblewrap firejail fuse3

# Arch Linux
sudo pacman -S bubblewrap firejail fuse3

Test Sandbox

# Test bubblewrap
bwrap --ro-bind / / --proc /proc --dev /dev --tmpfs /tmp echo "Sandbox works"

# Test firejail
firejail --version

Database Issues

Connection Failures

Symptoms:

“Connection refused” errors
Database timeout issues
Migration failures

Solutions:

Check Database Status

# PostgreSQL status
systemctl status postgresql

# Test connection
psql -h localhost -U pluggedin_user pluggedin_db

Verify Connection String

# Check environment variables
grep DATABASE_URL pluggedin-app/.env

# Test connection string
psql "$DATABASE_URL" -c "SELECT 1"

Common Fixes

# Restart PostgreSQL
systemctl restart postgresql

# Check available connections
psql -c "SELECT count(*) FROM pg_stat_activity WHERE datname = 'pluggedin_db'"

Migration Issues

Symptoms:

Migration command fails
Schema inconsistencies
Data corruption

Solutions:

Safe Migration Process

# Always backup first
pg_dump pluggedin_db > backup_$(date +%Y%m%d_%H%M%S).sql

# Run migration in transaction
pnpm db:migrate

# Verify migration
pnpm db:verify

Rollback Migration

# Rollback last migration
pnpm db:migrate:down

# Restore from backup if needed
psql pluggedin_db < backup_file.sql

Authentication Issues

API Key Problems

Symptoms:

401 Unauthorized errors
API requests failing
Cannot access protected endpoints

Solutions:

Verify API Key

# Check if key exists
grep PLUGGEDIN_API_KEY pluggedin-app/.env

# Test API key
curl -H "Authorization: Bearer $PLUGGEDIN_API_KEY" \
     https://plugged.in/api/profile

Generate New Key

# Generate new API key
openssl rand -hex 32

# Update environment
echo "PLUGGEDIN_API_KEY=new_key_here" >> pluggedin-app/.env

OAuth Issues

Symptoms:

Cannot authenticate with GitHub/Linear
OAuth callbacks failing
Token refresh issues

Solutions:

Check OAuth Configuration

# Verify OAuth settings
grep GITHUB_CLIENT_ID pluggedin-app/.env
grep LINEAR_CLIENT_ID pluggedin-app/.env

# Check OAuth URLs
grep NEXTAUTH_URL pluggedin-app/.env

Clear OAuth Sessions

# Clear corrupted sessions
pnpm db:query "DELETE FROM oauth_sessions WHERE expires_at < NOW()"

Performance Issues

Slow Response Times

Symptoms:

API calls taking >5 seconds
Web interface slow to load
High memory usage

Solutions:

Check Resource Usage

# Memory usage
free -h

# Disk usage
df -h

# Top processes
top -p $(pgrep -f pluggedin)

Database Optimization

# Analyze query performance
pnpm db:analyze

# Rebuild indexes
pnpm db:reindex

Cache Issues

# Clear application cache
rm -rf pluggedin-app/.next/cache

# Clear Redis cache (if using)
redis-cli FLUSHALL

High Memory Usage

Symptoms:

Out of memory errors
System becoming unresponsive
Frequent OOM killer events

Solutions:

Memory Optimization

# Check for memory leaks
pm2 monit

# Set memory limits
pm2 start pluggedin-app --max-memory-restart 1G

Garbage Collection

# Force garbage collection
curl http://localhost:12005/admin/gc

# Monitor GC stats
curl http://localhost:12005/admin/stats

File Upload Issues

Upload Failures

Symptoms:

File uploads timing out
“File too large” errors
Upload progress stuck

Solutions:

Check File Size Limits

# Current limits
grep MAX_FILE_SIZE pluggedin-app/.env

# Increase if needed
echo "MAX_FILE_SIZE=10485760" >> pluggedin-app/.env  # 10MB

Storage Space

# Check available space
df -h uploads/

# Clean old uploads if needed
find uploads/ -type f -mtime +30 -delete

Document Processing Issues

Symptoms:

Documents not appearing in search
RAG processing failures
Vector search not working

Solutions:

Check RAG Service

# RAG service status
systemctl status pluggedin-rag

# Test RAG processing
pnpm rag:test

Rebuild Search Index

# Rebuild vector index
pnpm rag:rebuild

# Test search functionality
pnpm rag:search "test query"

Network Issues

SSRF Protection Blocks

Symptoms:

Legitimate requests blocked
“SSRF attempt detected” errors
Cannot access internal resources

Solutions:

Check URL Validation

# Review blocked URLs
tail -f /var/log/pluggedin/security.log | grep SSRF

# Whitelist safe domains
echo "ALLOWED_DOMAINS=github.com,linear.app" >> pluggedin-app/.env

Debug Mode

# Enable debug logging
echo "DEBUG=pluggedin:*" >> pluggedin-app/.env

# Check validation logs
journalctl -u pluggedin-app -f | grep -i validation

Rate Limiting Issues

Symptoms:

429 Too Many Requests
API calls being throttled
Cannot perform bulk operations

Solutions:

Check Rate Limits

# Current limits
grep RATE_LIMIT pluggedin-app/.env

# Adjust if needed
echo "RATE_LIMIT_API=120" >> pluggedin-app/.env  # per minute

Redis Issues (if using Redis)

# Check Redis status
redis-cli ping

# Clear rate limit cache
redis-cli --scan --pattern "ratelimit:*" | xargs redis-cli DEL

Docker Issues

Container Issues

Symptoms:

Containers failing to start
Port conflicts
Volume mount issues

Solutions:

Check Docker Logs

# View container logs
docker logs pluggedin-app

# Check resource usage
docker stats pluggedin-app pluggedin-mcp

Common Fixes

# Clean up containers
docker system prune -f

# Restart containers
docker-compose restart

# Check port availability
netstat -tlnp | grep :12005

Security Issues

Encryption Issues

Symptoms:

Cannot decrypt sensitive data
“Invalid key” errors
Data corruption

Solutions:

Check Encryption Keys

# Verify encryption key exists
grep ENCRYPTION_KEY pluggedin-app/.env

# Generate new key if needed
openssl rand -base64 32

Migration Issues

# Check encryption migration status
pnpm db:query "SELECT COUNT(*) FROM servers WHERE command_encrypted IS NULL"

# Run encryption migration
pnpm migrate:encryption

XSS Protection Issues

Symptoms:

Content not displaying properly
Scripts being blocked
HTML content sanitized incorrectly

Solutions:

Check CSP Settings

# Review Content Security Policy
grep CSP_HEADER pluggedin-app/.env

# Adjust CSP if needed
echo "CSP_HEADER=default-src 'self'; script-src 'self' 'unsafe-inline'" >> pluggedin-app/.env

Getting Help

Log Collection

When reporting issues, include:

System Information

uname -a
node --version
npm --version
docker --version

Application Logs

# Last 100 lines of app logs
tail -n 100 /var/log/pluggedin/app.log

# MCP proxy logs
tail -n 100 /var/log/pluggedin/mcp.log

# Database logs
tail -n 100 /var/log/postgresql/postgresql.log

Configuration (without secrets)

# Environment variables (redacted)
env | grep -v SECRET | grep -v KEY | grep -v TOKEN

Support Channels

GitHub Issues: Bug Reports
Discussions: Community Help
Email: support@plugged.in
Emergency: security@plugged.in

Emergency Procedures

For critical production issues:

Immediate Actions
- Check system resources (CPU, memory, disk)
- Look for obvious errors in logs
- Test basic functionality
Quick Fixes
- Restart services: systemctl restart pluggedin-*
- Clear caches: rm -rf pluggedin-app/.next/cache
- Check database connectivity
Escalation
- Contact support with collected logs
- Provide steps to reproduce
- Include system specifications

Prevention

Monitoring Setup

# Set up log monitoring
journalctl -u pluggedin-app -f > /var/log/pluggedin/app.log &
journalctl -u pluggedin-mcp -f > /var/log/pluggedin/mcp.log &

# Set up alerting
# Monitor for common error patterns
grep -f error-patterns /var/log/pluggedin/*.log | \
  while read line; do
    echo "Error detected: $line" | mail -s "Plugged.in Error" admin@your-domain.com
  done

Regular Maintenance

# Daily health checks
pnpm health:check

# Weekly cleanup
find uploads/ -type f -mtime +30 -delete
pnpm db:cleanup

# Monthly optimization
pnpm db:optimize
pnpm cache:clean

This troubleshooting guide covers the most common issues. For additional help, consult the community discussions or contact support.

Getting Started

Platform Features

Tutorials

Security

Deployment

Testing

Migration Guides

Troubleshooting

Advanced Configuration

Integration Guides

Performance

​Troubleshooting Guide

​Quick Diagnostics

​Health Check Commands

​Common Status Codes

​MCP Server Issues

​”Session not found” Errors

​Tool Name Collisions

​Sandboxing Issues

​Database Issues

​Connection Failures

​Migration Issues

​Authentication Issues

​API Key Problems

​OAuth Issues

​Performance Issues

​Slow Response Times

​High Memory Usage

​File Upload Issues

​Upload Failures

​Document Processing Issues

​Network Issues

​SSRF Protection Blocks

​Rate Limiting Issues

​Docker Issues

​Container Issues

​Security Issues

​Encryption Issues

​XSS Protection Issues

​Getting Help

​Log Collection

​Support Channels

​Emergency Procedures

​Prevention

​Monitoring Setup

​Regular Maintenance

Troubleshooting Guide

Quick Diagnostics

Health Check Commands

Common Status Codes

MCP Server Issues

”Session not found” Errors

Tool Name Collisions

Sandboxing Issues

Database Issues

Connection Failures

Migration Issues

Authentication Issues

API Key Problems

OAuth Issues

Performance Issues

Slow Response Times

High Memory Usage

File Upload Issues

Upload Failures

Document Processing Issues

Network Issues

SSRF Protection Blocks

Rate Limiting Issues

Docker Issues

Container Issues

Security Issues

Encryption Issues

XSS Protection Issues

Getting Help

Log Collection

Support Channels

Emergency Procedures

Prevention

Monitoring Setup

Regular Maintenance