> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tydli.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

# Tydli Troubleshooting Guide

This guide helps you resolve common issues with the Tydli platform.

## 🚨 Common Issues

### Credential Issues

**Issue**: MCP Server returns 401 Unauthorized

* **Cause**: Invalid or expired API credentials
* **Solution**:
  1. Go to deployment settings
  2. Click "Test Credentials"
  3. If test fails, update credentials
  4. Re-test until successful
  5. See [Authentication Methods](/guides/authentication-methods) for details

**Issue**: Connection test passed but Claude fails

* **Cause**: Different endpoints have different requirements
* **Solution**:
  1. Check API documentation for endpoint-specific auth
  2. Verify all endpoints in OpenAPI spec use same auth
  3. Test multiple endpoints manually
  4. See [Authentication Methods](/guides/authentication-methods) for details

### File Upload Problems

**Issue**: File upload fails with "Invalid file format" error

* **Cause**: File is not a valid OpenAPI specification
* **Solution**:
  * Ensure file is JSON or YAML format
  * Verify OpenAPI version is 3.0 or higher
  * Check for syntax errors in the specification
  * **Alternative**: Use "✨ Any Format (AI)" tab to upload PDFs, docs, or other formats

**Issue**: File upload stuck at "Uploading..."

* **Cause**: Network timeout or file too large
* **Solution**:
  * Check file size (max 10MB for OpenAPI, 5MB for AI processing)
  * Try refreshing the page
  * Use paste method for large specifications

### AI Document Processing Issues

**Issue**: "Documentation quality insufficient" error

* **Cause**: AI couldn't extract enough structured API information
* **Solution**:
  * Ensure your docs include clear HTTP endpoints (GET, POST, etc.)
  * Add explicit parameter names and types
  * Specify the base URL of the API
  * Remove marketing content, focus on technical reference
  * → [See AI best practices](./AI_DOCUMENT_PROCESSING.md#best-practices-for-success)

**Issue**: "Daily limit reached" message

* **Cause**: You've used your 5 free AI conversions for today
* **Solution**:
  * Wait until midnight (your local time) for reset
  * Use OpenAPI upload directly if you have a spec (no limit)
  * Convert to OpenAPI manually using [Swagger Editor](https://editor.swagger.io)

**Issue**: Low confidence score (below 60%)

* **Cause**: Documentation lacks clear API structure
* **Solution**:
  * Review the preview to see what was extracted
  * Add missing endpoint details to your documentation
  * Try a different input format (paste vs upload)
  * Provide cleaner, more technical documentation

**Issue**: AI processing times out

* **Cause**: Document is too large or complex
* **Solution**:
  * Keep files under 5 MB
  * Extract just the API reference section
  * Split large documentation into parts
  * Try pasting key sections instead of uploading

### Validation Errors

**Issue**: "Missing required field: info.title"

* **Solution**: Add required OpenAPI fields:
  ```yaml theme={null}
  openapi: 3.0.1
  info:
    title: "Your API Title"
    version: "1.0.0"
  ```

**Issue**: "OpenAPI version must be 3.0 or higher"

* **Solution**: Update version in your specification:
  ```yaml theme={null}
  openapi: 3.0.1  # or 3.0.2, 3.0.3, etc.
  ```

### Deployment Issues

**Issue**: Deployment stuck in "Generating" status

* **Cause**: Server generation failed
* **Solution**:
  1. Check deployment logs for error details
  2. Verify OpenAPI specification is valid
  3. Try regenerating the deployment

**Issue**: MCP Server returns 404 errors

* **Cause**: Server not properly deployed or stopped
* **Solution**:
  1. Check deployment status is "Ready"
  2. Use "Health Check" to verify server is responding
  3. Restart deployment if needed

**Issue**: "Rate limit exceeded" errors

* **Cause**: Too many requests in short time period
* **Solution**: Wait a few minutes before retrying (check your dashboard for rate limit details)

### Authentication Problems

**Issue**: "Email verification required" error when logging in

* **Cause**: Account email not verified
* **Solution**:
  1. Check your email inbox for verification link
  2. Click the link to verify your email
  3. Return to the application and log in
  4. If link expired, contact support for new verification email

**Issue**: "Unauthorized" errors when managing deployments

* **Cause**: Session expired or invalid
* **Solution**:
  1. Sign out and sign back in
  2. Refresh the page
  3. Clear browser cache if problems persist

### Performance Issues

**Issue**: Dashboard loading slowly

* **Cause**: Large number of deployments or logs
* **Solution**:
  * Use deployment filters
  * Clear old deployment logs
  * Refresh the page

**Issue**: File validation takes too long

* **Cause**: Large or complex OpenAPI specification
* **Solution**:
  * Simplify specification if possible
  * Break large APIs into smaller specifications
  * Use URL import instead of file upload

## 🔧 Browser Issues

### Compatibility

* **Supported Browsers**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
* **JavaScript Required**: Ensure JavaScript is enabled
* **Ad Blockers**: May interfere with file uploads

### Cache Issues

If experiencing persistent problems:

1. Clear browser cache and cookies
2. Disable browser extensions temporarily
3. Try incognito/private browsing mode

## 📊 Getting Help

### Check System Status

* View deployment logs for detailed error information
* Use health check feature to verify server status
* Monitor deployment dashboard for real-time updates

### Reporting Issues

When reporting problems, include:

* Error messages (exact text)
* Browser and version
* Steps to reproduce
* OpenAPI specification (if applicable)

### Contact Support

* **Documentation**: Check [User Guide](/guides/user-guide)
* **API Reference**: See [API Reference](/api-reference/platform-api)
* **Status Page**: Monitor platform status

## 🔍 Advanced Troubleshooting

### Deployment Failed or Stuck

If your deployment fails or gets stuck in "Generating" status:

#### Check Your OpenAPI Spec

* **Ensure valid JSON or YAML format**: Use a validator before uploading
* **Verify all referenced schemas exist**: Check all `$ref` pointers
* **Check for circular references**: Avoid schemas that reference themselves
* **Test with a simple spec first**: Try the Petstore example to isolate issues

#### View Deployment Logs

1. Go to your deployment in the dashboard
2. Click "View Logs" to see detailed error messages
3. Look for validation errors or generation failures

**Quick fix:** Delete the failed deployment and try again with a simplified version of your spec. Add complexity gradually to identify the problematic section.

***

### Authentication Errors (401/403)

If your MCP server returns authentication errors:

#### Verify Credentials

* Double-check API key, username, or OAuth credentials
* Ensure credentials have not expired
* Test credentials directly with the target API using curl or Postman

```bash theme={null}
# Test API key authentication
curl -H "X-API-Key: YOUR_KEY" https://api.example.com/endpoint

# Test Bearer token
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/endpoint
```

#### Check Header Format

Make sure you're using the correct authentication header format:

```
Authorization: Bearer your-token-here
X-API-Key: your-key-here
Authorization: Basic base64-encoded-credentials
```

#### OAuth Troubleshooting

* Verify redirect URIs are correctly configured in your OAuth app settings
* Check that requested scopes are allowed for your application
* Ensure token refresh is working (check deployment logs for refresh attempts)
* Confirm client\_id and client\_secret are correct

***

### Claude Can't Find or Use MCP Server

If Claude doesn't recognize your MCP server:

#### Verify Configuration

1. Check the URL in `claude_desktop_config.json` is correct and complete
2. Ensure proper JSON formatting (no trailing commas, proper quotes)
3. Verify the auth token is present and correct
4. Confirm you restarted Claude Desktop after config changes (full quit + reopen)

#### Test Server URL

```bash theme={null}
# Test if server is accessible
curl https://your-project.supabase.co/functions/v1/mcp-router/your-slug

# Should return MCP server metadata (not an error)
```

If this returns an error, the issue is with your deployment, not Claude.

#### Check Claude Logs

Look for connection errors in Claude's log files:

* **Mac**: `~/Library/Logs/Claude/`
* **Windows**: `%APPDATA%\Claude\logs\`

Search for errors related to your MCP server name or URL.

***

### Rate Limit Errors (429)

If you're hitting rate limits:

#### Check Your Plan Limits

View current usage in **Settings → Billing**:

* **Free tier**: 1,000 requests/month, 20 requests/hour
* **Pro tier**: 50,000 requests/month, 200 requests/hour
* **Enterprise**: Custom limits

#### Optimize API Calls

Reduce the number of requests:

* **Batch multiple operations** when possible (combine requests)
* **Cache responses** in your application or Claude's context
* **Use webhooks instead of polling** when available
* **Implement pagination** for large data sets
* **Only request necessary fields** using field selectors

***

### IP Blocked Errors (403)

If you receive an "IP address blocked" error:

#### Possible Causes

* Your IP exceeded rate limits multiple times
* Your IP was manually blocked by an administrator
* Suspicious activity was detected from your IP

#### Solutions

1. **Wait and retry** - Temporary blocks may expire automatically
2. **Check your usage patterns** - Ensure you're not making excessive requests
3. **Contact support** - If you believe the block is in error
4. **Use authentication** - Authenticated endpoints have different rate limits

#### For API Consumers

If your users report 403 errors:

* Check your MCP server's authentication configuration
* Consider implementing user-level authentication instead of public access
* Review your rate limit settings in the dashboard

***

### Request Timeouts

If requests are timing out:

#### Check Target API Performance

* Test the target API directly to measure response time
* Some endpoints may naturally take longer (data exports, reports)
* Consider async patterns for long-running operations

#### MCP Timeout Limits

Default timeout is **30 seconds per request**. For longer operations:

* Break large operations into smaller chunks
* Use pagination for large data sets (e.g., limit to 100 items per request)
* Implement async job patterns with status polling:
  1. Start job → Get job ID
  2. Poll status → Check if complete
  3. Retrieve results → When ready

***

### OpenAPI Spec Validation Issues

#### Common Validation Errors

**Missing required fields**:

```yaml theme={null}
openapi: 3.1.0
info:
  title: "Your API Title"  # Required
  version: "1.0.0"          # Required
paths: {}                    # Required (can't be empty)
```

**Invalid \$ref references**:

```yaml theme={null}
# Bad - schema doesn't exist
components:
  schemas:
    User:
      $ref: '#/components/schemas/NonExistentSchema'

# Good - schema exists
components:
  schemas:
    User:
      $ref: '#/components/schemas/Profile'
    Profile:
      type: object
```

**Circular schema definitions**:

```yaml theme={null}
# Bad - creates infinite loop
components:
  schemas:
    A:
      $ref: '#/components/schemas/B'
    B:
      $ref: '#/components/schemas/A'
```

**Malformed URLs in servers section**:

```yaml theme={null}
# Bad
servers:
  - url: not-a-valid-url

# Good
servers:
  - url: https://api.example.com/v1
```

#### Validation Tools

Use these tools to validate your spec before deploying:

* **JSON**: [jsonlint.com](https://jsonlint.com)
* **YAML**: [yamllint.com](https://yamllint.com)
* **OpenAPI**: [editor.swagger.io](https://editor.swagger.io)

***

## 🔍 Advanced Debugging

### Database Query Debugging

**Check deployment logs for errors:**

```sql theme={null}
SELECT * FROM deployment_logs
WHERE deployment_id = 'your-deployment-id'
AND status = 'failure'
ORDER BY created_at DESC
LIMIT 20;
```

**Find slow API endpoints:**

```sql theme={null}
SELECT
  path,
  AVG(response_time_ms) as avg_ms,
  MAX(response_time_ms) as max_ms,
  COUNT(*) as request_count
FROM request_usage_tracking
WHERE deployment_id = 'your-deployment-id'
  AND response_time_ms IS NOT NULL
GROUP BY path
ORDER BY avg_ms DESC
LIMIT 10;
```

**Check authentication failures:**

```sql theme={null}
SELECT * FROM deployment_logs
WHERE deployment_id = 'your-deployment-id'
  AND operation = 'authentication'
  AND status = 'failure'
ORDER BY created_at DESC;
```

**Monitor error rate:**

```sql theme={null}
SELECT
  DATE_TRUNC('hour', created_at) as hour,
  status,
  COUNT(*) as count
FROM deployment_logs
WHERE deployment_id = 'your-deployment-id'
  AND created_at > NOW() - INTERVAL '24 hours'
GROUP BY hour, status
ORDER BY hour DESC;
```

**Find requests with errors:**

```sql theme={null}
SELECT
  path,
  response_status,
  COUNT(*) as error_count
FROM request_usage_tracking
WHERE deployment_id = 'your-deployment-id'
  AND response_status >= 400
GROUP BY path, response_status
ORDER BY error_count DESC;
```

### Development Mode

For developers using the platform:

1. Open browser developer tools (F12)
2. Check Console tab for JavaScript errors
3. Monitor Network tab for failed requests
4. Check Application tab for local storage issues

### API Debugging

* Test MCP endpoints directly using curl
* Verify JWT tokens are valid
* Check CORS headers for cross-origin issues

***

## 📚 Additional Resources

For more help, check these guides:

* **[FAQ](/support/faq)**: Frequently asked questions
* **[Getting Help](/community/getting-help)**: How to get support
* **[Best Practices](/guides/best-practices)**: Avoid common pitfalls
* **[Authentication Methods](/guides/authentication-methods)**: Auth troubleshooting

***

*For additional support, consult the complete documentation or contact the development team.*