Troubleshooting Guide

⚡ Quick Diagnostics

📤 Upload & Validation Issues

Problem: File Won't Upload

Solutions:

1. Check file size: Maximum file size is 10MB

   # Check file size on Linux/Mac
   ls -lh your-openapi.json
   
   # Check file size on Windows
   dir your-openapi.json

2. Verify file format: Only JSON and YAML files are accepted
   • Ensure file extension is .json, .yaml, or .yml
   • Rename file if needed (e.g., openapi.txt → openapi.json)
3. Check browser console for specific errors:
   • Press F12 → Console tab
   • Look for red error messages
   • Take a screenshot for support if needed

Problem: Validation Errors

Solutions:

1. Validate your OpenAPI spec using online tools:
   • Swagger Editor
   • Swagger CLI
2. Common validation fixes:
   openapi.yaml

   # Ensure these required fields exist:
   openapi: "3.0.0"  # or "3.1.0"
   info:
     title: "Your API Title"
     version: "1.0.0"
   paths:
     /endpoint:
       get:
         summary: "Endpoint description"
         responses:
           200:
             description: "Success"

3. Convert Swagger 2.0 to OpenAPI 3.0:

   # Using npm tool
   npm install -g swagger2openapi
   swagger2openapi swagger.json > openapi.json

Problem: Endpoints Not Detected

1. Ensure your spec has a paths object with at least one endpoint
2. Verify endpoints have valid HTTP methods (GET, POST, PUT, DELETE, etc.)
3. Check for syntax errors in the paths section

⚙️ Mapping Configuration Issues

Problem: Tool Names Not Updating

Symptoms:

• Clicking save doesn't update the tool name
• Changes revert after page refresh
• Edit button is unresponsive

Solutions:

1. Check for validation errors:
   • Tool names must be lowercase with underscores
   • No spaces or special characters allowed
   • Example: get_user_profile ✅ vs Get User Profile ❌
2. Wait for save confirmation:
   • Look for green checkmark or "Saved" message
   • Don't navigate away immediately after editing
3. Network issues:
   • Check browser console for failed requests
   • Verify internet connection
   • Try again after a few seconds

Problem: Can't Exclude Endpoints

1. Refresh the page and try again
2. Check if you have edit permissions (project owner)
3. Ensure JavaScript is enabled in your browser
4. Try a different browser to isolate the issue

📥 Generation Problems

Problem: Code Generation Fails

Solutions:

1. Verify Target API URL:
   • Must be a valid URL (https://api.example.com)
   • Should not end with a slash
   • Must be accessible (not localhost for cloud generation)
2. Check included endpoints:
   • At least one endpoint must be included
   • Excluded endpoints won't be in generated code
3. Review special characters:
   • Tool descriptions shouldn't contain quotes or backticks
   • Use plain text without markdown

Problem: Download Doesn't Start

Browser Settings to Check:

🔐 Authentication Issues

Problem: Can't Log In

Email/Password Login Issues:

1. Password reset:
   • Click "Forgot Password?" on login page
   • Check email (including spam folder)
   • Reset link expires in 1 hour
2. Account verification:
   • New accounts require email verification
   • Check for verification email
   • Request new verification email if needed

Problem: Google Login Fails

Solutions:

1. Browser settings:
   • Enable third-party cookies for MigrateForce
   • Disable aggressive tracking protection temporarily
   • Whitelist migrateforce.com in ad blockers
2. Google account issues:
   • Ensure Google account is active
   • Check for 2FA requirements
   • Try logging into Google first, then MigrateForce

📁 Project Management Issues

Problem: Projects Not Loading

Solutions:

1. Wait 10-15 seconds for initial load
2. Refresh the page (Ctrl+R or Cmd+R)
3. Check network tab for failed requests
4. Log out and log back in
5. Clear browser cache for MigrateForce

Problem: Can't Delete Project

Checklist:

• Ensure you're the project owner
• Remove any active MCP server deployments first
• Unshare project from team members
• Wait for any pending operations to complete

🌐 Browser-Specific Issues

❌ Error Messages Explained

🔧 Advanced Troubleshooting

Enable Debug Mode

For detailed logging, enable debug mode in your browser:

// Run this in browser console (F12)
localStorage.setItem('MIGRATEFORCE_DEBUG', 'true');
location.reload();

// To disable debug mode
localStorage.removeItem('MIGRATEFORCE_DEBUG');

Performance Issues

1. Check browser performance:
   • Close unnecessary tabs (limit to 10-15)
   • Disable resource-heavy extensions
   • Clear browser cache regularly
2. Optimize your OpenAPI spec:
   • Remove unused schemas
   • Minimize example data
   • Split large specs into smaller ones
3. Network optimization:
   • Use stable, high-speed connection
   • Avoid VPNs if experiencing issues
   • Try during off-peak hours

Debugging Network Issues

# Test connectivity to MigrateForce
ping migrateforce.com

# Check DNS resolution
nslookup migrateforce.com

# Test HTTPS connection
curl -I https://migrateforce.com

# Check for proxy issues
echo $HTTP_PROXY
echo $HTTPS_PROXY

💬 Getting Support

Before Contacting Support

Contact Methods

Recovery Procedures

🎯 Quick Fixes Summary