yoda-mcp/docs/guides/troubleshooting.md

Intelligent Planning MCP with Optional Dependencies and Graceful Fallbacks - wise planning through the Force of lean excellence

# Planner MCP Troubleshooting Guide

## Overview

This comprehensive troubleshooting guide helps you diagnose and resolve common issues with the Planner MCP system. Issues are organized by category with step-by-step resolution procedures.

## Quick Diagnostic Commands

Before diving into specific issues, run these diagnostic commands:

```bash
# Check overall system status
planner-mcp status

# Verify authentication
planner-mcp auth test

# Check service health
planner-mcp health check

# View recent logs
planner-mcp logs --last 1h

# Run system diagnostics
planner-mcp diagnose --full
```

## Authentication and Authorization Issues

### Problem: Authentication Failed

**Symptoms:**
- "Invalid credentials" error messages
- 401 Unauthorized responses
- Unable to access protected endpoints

**Diagnostic Steps:**
1. **Check Credentials**
   ```bash
   # Verify API key is set
   echo $PLANNER_MCP_API_KEY
   
   # Test authentication
   planner-mcp auth test
   
   # View current auth status
   planner-mcp auth status
   ```

2. **Check Token Expiration**
   ```bash
   # View token details
   planner-mcp auth inspect
   
   # Refresh expired token
   planner-mcp auth refresh
   ```

3. **Verify API Endpoint**
   ```bash
   # Check configured endpoint
   planner-mcp config get endpoint
   
   # Test endpoint connectivity
   curl -I https://api.planner-mcp.example.com/health
   ```

**Solutions:**
- **Invalid API Key**: Generate new API key in dashboard
- **Expired Token**: Run `planner-mcp auth refresh`
- **Wrong Endpoint**: Update with `planner-mcp config set endpoint <correct_url>`
- **Network Issues**: Check firewall/proxy settings

### Problem: Permission Denied

**Symptoms:**
- 403 Forbidden responses
- "Insufficient permissions" errors
- Cannot access certain features

**Diagnostic Steps:**
```bash
# Check your user role
planner-mcp auth whoami

# View available permissions
planner-mcp auth permissions

# Test specific permission
planner-mcp auth can-i create plans
```

**Solutions:**
- **Insufficient Role**: Request role upgrade from admin
- **Feature Not Available**: Check subscription tier
- **Resource Access**: Verify ownership or shared access

## Plan Creation Issues

### Problem: Plan Creation Fails

**Symptoms:**
- Plan creation timeouts
- Validation errors
- Poor quality scores

**Diagnostic Steps:**
1. **Validate Request Format**
   ```bash
   # Validate request JSON
   planner-mcp validate --file request.json
   
   # Check required fields
   planner-mcp schema show PlanningRequest
   ```

2. **Check MCP Server Health**
   ```bash
   # Test MCP server connectivity
   planner-mcp mcp health
   
   # View current capability tier
   planner-mcp capability status
   ```

3. **Review Requirements Quality**
   ```bash
   # Analyze requirement quality
   planner-mcp analyze requirements --file requirements.txt
   
   # Get improvement suggestions
   planner-mcp requirements enhance --file requirements.txt
   ```

**Common Fixes:**

#### Vague Requirements
```bash
# Bad example
"Build a good app"

# Good example
"Build a task management application with user authentication, 
CRUD operations for tasks, categorization, priority levels, 
and mobile-responsive design"
```

#### Invalid Complexity Level
```javascript
// Correct complexity values
complexity: 'simple' | 'moderate' | 'complex' | 'enterprise' | 'world_class'
```

#### Missing Context
```javascript
// Add relevant context
context: {
  technologies: ['React', 'Node.js'],
  constraints: ['Budget: $10k', 'Timeline: 8 weeks'],
  existing_system: 'Legacy PHP application',
  team_size: 3
}
```

### Problem: Low Quality Scores

**Symptoms:**
- Quality scores below expectations
- Plans lack detail or specificity
- Missing implementation guidance

**Diagnostic Process:**
1. **Analyze Quality Breakdown**
   ```bash
   # View detailed quality analysis
   planner-mcp plans analyze plan_123 --quality
   
   # Compare with quality benchmarks
   planner-mcp quality benchmark --plan plan_123
   ```

2. **Enhancement Suggestions**
   ```bash
   # Get specific enhancement recommendations
   planner-mcp plans enhance plan_123 --analyze
   
   # Apply automatic enhancements
   planner-mcp plans enhance plan_123 --auto-apply
   ```

**Quality Improvement Strategies:**

#### Requirement Completeness (20% weight)
- ✅ **Cover all functional requirements**
- ✅ **Specify non-functional requirements**
- ✅ **Include acceptance criteria**
- ✅ **Define user stories and use cases**

#### Technical Accuracy (18% weight)
- ✅ **Use appropriate technology stack**
- ✅ **Consider scalability and performance**
- ✅ **Address security requirements**
- ✅ **Include error handling strategies**

#### Implementation Detail (12% weight)
- ✅ **Provide step-by-step implementation**
- ✅ **Include code examples and patterns**
- ✅ **Specify configuration details**
- ✅ **Detail deployment procedures**

## Performance Issues

### Problem: Slow Response Times

**Symptoms:**
- Plan creation takes longer than 30 seconds
- API requests timeout
- UI becomes unresponsive

**Diagnostic Steps:**
1. **Check System Load**
   ```bash
   # View current system metrics
   planner-mcp metrics system
   
   # Check queue depth
   planner-mcp metrics queue
   
   # View response time trends
   planner-mcp metrics response-time --period 24h
   ```

2. **Analyze Request Complexity**
   ```bash
   # Estimate processing time
   planner-mcp estimate --request request.json
   
   # View complexity breakdown
   planner-mcp analyze complexity --request request.json
   ```

**Performance Optimization:**
- **Reduce Complexity**: Lower complexity level if acceptable
- **Simplify Requirements**: Break large requests into smaller ones
- **Use Batch Processing**: Combine multiple small requests
- **Enable Caching**: Use cached results when possible

### Problem: Rate Limiting

**Symptoms:**
- 429 Too Many Requests errors
- Requests being throttled
- Delayed processing

**Resolution:**
```bash
# Check current rate limits
planner-mcp limits show

# View usage statistics
planner-mcp usage stats

# Request limit increase
planner-mcp support request-limit-increase \
  --current-usage "1000 req/hour" \
  --requested-limit "2000 req/hour" \
  --justification "Increased team size"
```

## System Connectivity Issues

### Problem: MCP Server Unavailable

**Symptoms:**
- Fallback mode activated
- Reduced system capabilities
- Missing plan components

**Diagnostic Steps:**
```bash
# Check MCP server status
planner-mcp mcp status --server serena
planner-mcp mcp status --server sequential
planner-mcp mcp status --server context7
planner-mcp mcp status --server todolist

# Test direct connectivity
planner-mcp mcp ping --server serena

# View capability tier
planner-mcp capability current
```

**Resolution:**
1. **Wait for Recovery**: System will automatically recover when servers are available
2. **Check Status Page**: Visit [status.planner-mcp.example.com](https://status.planner-mcp.example.com)
3. **Report Persistent Issues**: Contact support if servers remain unavailable

### Problem: Network Connectivity

**Symptoms:**
- Connection timeouts
- DNS resolution failures
- SSL/TLS errors

**Network Diagnostics:**
```bash
# Test basic connectivity
curl -I https://api.planner-mcp.example.com/health

# Check DNS resolution
nslookup api.planner-mcp.example.com

# Test SSL certificate
openssl s_client -connect api.planner-mcp.example.com:443

# Trace network route
traceroute api.planner-mcp.example.com
```

**Common Fixes:**
- **Firewall Blocking**: Whitelist Planner MCP endpoints
- **Proxy Configuration**: Configure proxy settings
- **DNS Issues**: Use public DNS servers (8.8.8.8, 1.1.1.1)
- **SSL Problems**: Update certificates or bypass SSL validation for testing

## Data and Configuration Issues

### Problem: Configuration Errors

**Symptoms:**
- "Configuration invalid" errors
- Service startup failures
- Unexpected behavior

**Configuration Debugging:**
```bash
# View current configuration
planner-mcp config show

# Validate configuration
planner-mcp config validate

# Reset to defaults
planner-mcp config reset

# Export configuration
planner-mcp config export --file current-config.json
```

**Configuration Fixes:**
- **Invalid Format**: Ensure JSON syntax is correct
- **Missing Required Fields**: Add all required configuration values
- **Environment Variables**: Check environment variable names and values
- **File Permissions**: Ensure config files are readable

### Problem: Data Synchronization Issues

**Symptoms:**
- Inconsistent plan data
- Missing or outdated information
- Synchronization errors

**Data Diagnostics:**
```bash
# Check data consistency
planner-mcp data verify --plan plan_123

# Force data refresh
planner-mcp data refresh --plan plan_123

# View synchronization status
planner-mcp sync status
```

## Integration Issues

### Problem: Webhook Failures

**Symptoms:**
- Webhook events not received
- Webhook timeouts
- Authentication failures for webhooks

**Webhook Debugging:**
```bash
# List configured webhooks
planner-mcp webhooks list

# Test webhook endpoint
planner-mcp webhooks test --url https://your-app.com/webhook

# View webhook logs
planner-mcp webhooks logs --webhook webhook_123

# Retry failed webhooks
planner-mcp webhooks retry --webhook webhook_123
```

**Webhook Fixes:**
- **Endpoint Unreachable**: Verify URL accessibility
- **Authentication Issues**: Check webhook secret
- **Timeout Issues**: Optimize webhook handler performance
- **SSL Problems**: Ensure valid SSL certificates

### Problem: Third-Party Integration

**Symptoms:**
- API integration failures
- Data format mismatches
- Authentication issues with external services

**Integration Debugging:**
```bash
# Test external API connectivity
planner-mcp integrations test --service jira

# View integration logs
planner-mcp integrations logs --service slack

# Refresh integration credentials
planner-mcp integrations refresh --service github
```

## Error Messages and Codes

### Common Error Codes

| Code | Meaning | Common Causes | Solutions |
|------|---------|---------------|-----------|
| 400 | Bad Request | Invalid request format | Validate request JSON |
| 401 | Unauthorized | Invalid credentials | Check API key and refresh token |
| 403 | Forbidden | Insufficient permissions | Verify role and permissions |
| 404 | Not Found | Resource doesn't exist | Check resource ID and ownership |
| 409 | Conflict | Resource already exists | Use update instead of create |
| 429 | Too Many Requests | Rate limit exceeded | Reduce request frequency |
| 500 | Internal Server Error | System error | Check system status and retry |
| 503 | Service Unavailable | System overloaded | Wait and retry with backoff |

### Detailed Error Analysis

**Error Format:**
```json
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Plan validation failed",
    "details": {
      "field": "requirements",
      "issue": "Requirements too vague",
      "suggestion": "Provide more specific requirements"
    },
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

**Common Error Patterns:**

#### Validation Errors
```bash
# View validation details
planner-mcp errors explain VALIDATION_FAILED

# Fix validation issues
planner-mcp validate --fix request.json
```

#### Resource Errors
```bash
# Check resource availability
planner-mcp resources check --plan plan_123

# View resource limits
planner-mcp resources limits
```

## Performance Monitoring

### Monitoring Commands

```bash
# View performance metrics
planner-mcp metrics performance --live

# Check resource usage
planner-mcp metrics resources

# Monitor plan creation times
planner-mcp metrics timing --operation create_plan

# View error rates
planner-mcp metrics errors --period 24h
```

### Performance Baselines

| Metric | Target | Warning | Critical |
|--------|--------|---------|----------|
| Response Time (P95) | < 2s | > 5s | > 10s |
| Plan Creation | < 30s | > 60s | > 120s |
| Error Rate | < 1% | > 5% | > 10% |
| Availability | > 99.9% | < 99% | < 95% |

## Log Analysis

### Log Levels and Interpretation

```bash
# View error logs
planner-mcp logs --level error --last 24h

# Filter by component
planner-mcp logs --component orchestrator --last 1h

# Search for specific issues
planner-mcp logs --search "validation failed" --last 6h

# Export logs for analysis
planner-mcp logs --format json --output logs.json
```

### Common Log Patterns

#### Successful Plan Creation
```
INFO  [Orchestrator] Plan creation started: plan_abc123
INFO  [MCPManager] All MCP servers available (Premium tier)
INFO  [Validator] Plan validation passed (score: 92)
INFO  [Orchestrator] Plan creation completed: plan_abc123 (28.5s)
```

#### Fallback Mode Activation
```
WARN  [MCPManager] Serena MCP unavailable, switching to Enhanced tier
INFO  [Orchestrator] Fallback mode activated: Enhanced (3/4 servers)
INFO  [Validator] Plan quality adjusted for reduced capability
```

#### Authentication Issues
```
ERROR [Auth] JWT token expired for user: user@example.com
ERROR [Auth] Authentication failed: Invalid API key
WARN  [RateLimit] Rate limit exceeded for user: user@example.com
```

## Recovery Procedures

### System Recovery

```bash
# Restart all services
planner-mcp system restart

# Clear cache and reset state
planner-mcp system reset --clear-cache

# Run health checks
planner-mcp system health --full

# Restore from backup
planner-mcp system restore --backup backup_20240115
```

### Data Recovery

```bash
# Recover corrupted plan
planner-mcp data recover --plan plan_123

# Restore deleted plan
planner-mcp data restore --plan plan_123 --from-backup

# Rebuild search index
planner-mcp data reindex --type plans
```

## Getting Additional Help

### Support Channels

#### Self-Service Resources
- **Knowledge Base**: [docs.planner-mcp.example.com](https://docs.planner-mcp.example.com)
- **Community Forum**: [community.planner-mcp.example.com](https://community.planner-mcp.example.com)
- **Video Tutorials**: [tutorials.planner-mcp.example.com](https://tutorials.planner-mcp.example.com)
- **FAQ**: [faq.planner-mcp.example.com](https://faq.planner-mcp.example.com)

#### Direct Support
- **Email Support**: support@planner-mcp.example.com
- **Live Chat**: Available in dashboard (business hours)
- **Phone Support**: +1-800-PLANNER (premium support)
- **Slack Community**: #planner-support

#### Emergency Support
- **24/7 Emergency**: emergency@planner-mcp.example.com
- **Status Updates**: [status.planner-mcp.example.com](https://status.planner-mcp.example.com)
- **Incident Reports**: [incidents.planner-mcp.example.com](https://incidents.planner-mcp.example.com)

### Creating Support Tickets

```bash
# Create a support ticket
planner-mcp support create-ticket \
  --type technical \
  --priority high \
  --title "Plan creation failing with timeout" \
  --description "Detailed description of the issue..." \
  --attach logs.json

# Include diagnostic information
planner-mcp support create-ticket \
  --type technical \
  --include-diagnostics \
  --include-logs \
  --include-config
```

### Information to Include

When contacting support, please provide:
- **Request ID**: From error responses
- **Timestamp**: When the issue occurred
- **User ID**: Your account identifier
- **Plan ID**: If related to a specific plan
- **Browser/Client**: Version and type
- **Steps to Reproduce**: Exact steps that cause the issue
- **Error Messages**: Complete error messages
- **Log Files**: Relevant log entries
- **Environment**: Development, staging, or production

---

**Still Having Issues?**

If this guide doesn't resolve your problem:
1. Check the [status page](https://status.planner-mcp.example.com) for known issues
2. Search the [community forum](https://community.planner-mcp.example.com) for similar problems
3. Contact our support team with detailed information about your issue

**Last Updated**: {current_date}  
**Version**: 2.0  
**Feedback**: [docs-feedback@planner-mcp.example.com](mailto:docs-feedback@planner-mcp.example.com)