Troubleshooting Guide

Quick Diagnostics

Before diving into specific issues, run these quick checks:

Check API Key

Verify your API key is valid and active

curl -H "Authorization: Bearer <your-api-key>" \
     https://api.agentflare.com/v1/health

Check Network Connectivity

Ensure you can reach Agentflare services

curl -I https://api.agentflare.com
curl -I https://<your-workspace>.agentflare.com

Verify Environment Variables

Check that required environment variables are set

echo $API_JWT_SECRET
echo $AGENTFLARE_PROJECT_ID

Common Issues & Solutions

Authentication & Authorization

401 Unauthorized Error

Symptoms:

Getting 401 errors when making API calls
“Invalid API key” messages
Authentication failures in dashboard

Common Causes:

Invalid or expired API key
API key not included in request headers
Using wrong authentication format

Solutions:

Verify API Key Format:

// Correct format
const client = new AgentflareClient({
  apiKey: "af_live_1234567890abcdef", // Must start with af_
  projectId: "proj_abc123"
});

// Check headers format
headers: {
  "Authorization": "Bearer af_live_1234567890abcdef"
}

Regenerate API Key:

Go to Dashboard → Settings → API Keys
Delete old key and create new one
Update environment variables

Check Key Permissions:

Ensure key has required scopes
Verify key is active (not disabled)

Debug Commands:

# Test API key validity
curl -H "Authorization: Bearer $API_JWT_SECRET" \
     https://api.agentflare.com/v1/auth/verify

# Check key permissions
curl -H "Authorization: Bearer $API_JWT_SECRET" \
     https://api.agentflare.com/v1/auth/permissions

403 Forbidden Error

Symptoms:

Getting 403 errors despite valid authentication
“Insufficient permissions” messages
Access denied to specific resources

Solutions:

Check API Key Scopes:

// Ensure your API key has required scopes
const requiredScopes = [
  "tools:read",
  "tools:write", 
  "servers:read",
  "servers:write",
  "analytics:read"
];

Verify Project Access:

Ensure project ID is correct
Check you have access to the project
Verify project is active

Check Rate Limits:

Review current usage vs. plan limits
Implement exponential backoff
Consider upgrading plan

Connection Issues

Connection Timeouts

Symptoms:

Requests timing out
“Connection timed out” errors
Slow response times

Diagnostic Steps:

Check Network Latency:

# Test latency to Agentflare
ping api.agentflare.com

# Test HTTPS connectivity
curl -w "Connect: %{time_connect}s, Total: %{time_total}s\n" \
     -o /dev/null -s https://api.agentflare.com/v1/health

Verify Firewall/Proxy Settings:

# Check if corporate proxy is blocking
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Test direct vs proxy connection
curl --noproxy "*" https://api.agentflare.com/v1/health

Solutions:

Increase Timeout Values:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  timeout: 60000, // 60 seconds
  retries: 3
});

Configure Proxy Settings:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  proxy: {
    host: "your-proxy.com",
    port: 8080,
    auth: "username:password"
  }
});

Enable Connection Pooling:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  connectionPool: {
    maxConnections: 10,
    keepAlive: true,
    timeout: 30000
  }
});

SSL/TLS Certificate Errors

Symptoms:

“SSL certificate verification failed”
“CERTIFICATE_VERIFY_FAILED” errors
Connection refused with HTTPS

Solutions:

Update Certificates:

# Update system certificates
sudo apt-get update && sudo apt-get install ca-certificates

# For macOS
brew install ca-certificates

# For Node.js apps
npm update

Configure Certificate Validation:

// For development only - DO NOT use in production
process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0";

// Better solution - specify certificate bundle
const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  tls: {
    ca: fs.readFileSync('/path/to/ca-bundle.crt')
  }
});

Tool Call Issues

Tool Calls Not Appearing in Dashboard

Symptoms:

Tool calls execute successfully
No data appears in Agentflare dashboard
Missing observability data

Diagnostic Steps:

Check Client Configuration:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  projectId: process.env.AGENTFLARE_PROJECT_ID, // Required!
  enableObservability: true, // Ensure enabled
  debug: true // Enable debug logging
});

Verify Data Flow:

// Add debug logging
client.on('toolCall', (data) => {
  console.log('Tool call captured:', data);
});

client.on('error', (error) => {
  console.error('Agentflare error:', error);
});

Solutions:

Enable Debug Mode:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  projectId: process.env.AGENTFLARE_PROJECT_ID,
  debug: true,
  logLevel: 'debug'
});

Check Sampling Rate:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  projectId: process.env.AGENTFLARE_PROJECT_ID,
  sampling: {
    rate: 1.0 // 100% sampling for troubleshooting
  }
});

Manual Data Flush:

// Force flush buffered data
await client.flush();

// Or disable batching temporarily
const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  projectId: process.env.AGENTFLARE_PROJECT_ID,
  batching: {
    enabled: false
  }
});

Tool Call Failures

Symptoms:

Tool calls fail with errors
“Tool not found” messages
Unexpected response formats

Diagnostic Steps:

Test Direct Server Connection:

// Test without Agentflare proxy
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const directClient = new Client({
  transport: new StdioServerTransport({
    command: "your-mcp-server",
    args: ["--config", "config.json"]
  })
});

try {
  await directClient.connect();
  const result = await directClient.callTool({
    name: "test-tool",
    arguments: {}
  });
  console.log("Direct connection works:", result);
} catch (error) {
  console.error("Direct connection failed:", error);
}

Check Server Health:

# For HTTP servers
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"method": "tools/list"}' \
     https://your-mcp-server.com/mcp

# Check server logs
tail -f /var/log/mcp-server.log

Solutions:

Add Error Handling:

try {
  const result = await client.callTool({
    name: "search",
    arguments: { query: "test" },
    timeout: 30000,
    retries: 3
  });
} catch (error) {
  if (error.code === 'TOOL_NOT_FOUND') {
    console.log('Available tools:', await client.listTools());
  } else if (error.code === 'TIMEOUT') {
    console.log('Tool call timed out, trying with longer timeout');
  }
  throw error;
}

Validate Arguments:

// Validate tool arguments before calling
const toolSchema = await client.getToolSchema('search');

const result = await client.callTool({
  name: "search",
  arguments: validateArguments(toolSchema, { query: "test" })
});

Performance Issues

High Latency

Symptoms:

Slow tool call responses
High response times in dashboard
Performance degradation over time

Diagnostic Steps:

Measure Components:

const startTime = Date.now();

const result = await client.callTool({
  name: "search",
  arguments: { query: "test" },
  metadata: {
    startTime: startTime
  }
});

const endTime = Date.now();
console.log(`Total time: ${endTime - startTime}ms`);

Check Network Performance:

# Measure network latency
curl -w "DNS: %{time_namelookup}s, Connect: %{time_connect}s, Total: %{time_total}s\n" \
     -o /dev/null -s https://api.agentflare.com/v1/health

Solutions:

Enable Connection Pooling:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  connectionPool: {
    maxConnections: 20,
    keepAlive: true,
    timeout: 30000
  }
});

Optimize Batching:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  batching: {
    enabled: true,
    size: 10,
    timeout: 1000
  }
});

Use Regional Endpoints:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  endpoint: "https://us-east-1.api.agentflare.com/v1" // Use closest region
});

Memory Leaks

Symptoms:

Increasing memory usage over time
Application becomes unresponsive
Out of memory errors

Diagnostic Steps:

Monitor Memory Usage:

// Add memory monitoring
setInterval(() => {
  const usage = process.memoryUsage();
  console.log('Memory usage:', {
    rss: `${Math.round(usage.rss / 1024 / 1024)} MB`,
    heapTotal: `${Math.round(usage.heapTotal / 1024 / 1024)} MB`,
    heapUsed: `${Math.round(usage.heapUsed / 1024 / 1024)} MB`
  });
}, 30000);

Solutions:

Proper Client Cleanup:

// Always cleanup clients
process.on('SIGINT', async () => {
  await client.close();
  process.exit(0);
});

// For long-running processes
const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  autoCleanup: true,
  maxBufferSize: 1000
});

Limit Buffer Sizes:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  buffers: {
    maxSize: 1000,
    flushInterval: 5000,
    autoFlush: true
  }
});

Environment-Specific Issues

Development Environment

Local Development Setup

Common Issues:

Environment variables not loaded
Local MCP servers not accessible
Development vs production configuration

Solutions:

Environment Variable Management:

# Use dotenv for local development
npm install dotenv

// At the top of your main file
import 'dotenv/config';

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  projectId: process.env.AGENTFLARE_PROJECT_ID,
  environment: process.env.NODE_ENV || 'development'
});

Local Server Configuration:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  servers: [{
    name: "local-server",
    transport: "stdio",
    command: "./local-mcp-server",
    args: ["--dev", "--verbose"]
  }]
});

Production Environment

Production Deployment Issues

Common Issues:

Different behavior in production
Environment variable access
Performance under load

Solutions:

Production Configuration:

const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  projectId: process.env.AGENTFLARE_PROJECT_ID,
  environment: 'production',
  logLevel: 'warn', // Reduce logging in production
  sampling: {
    rate: 0.1 // 10% sampling for high-volume production
  }
});

Health Checks:

// Add health check endpoint
app.get('/health', async (req, res) => {
  try {
    await client.ping();
    res.status(200).json({ status: 'healthy' });
  } catch (error) {
    res.status(500).json({ status: 'unhealthy', error: error.message });
  }
});

Debug Tools & Commands

CLI Debugging

# Test API connectivity
curl -H "Authorization: Bearer $API_JWT_SECRET" \
     https://api.agentflare.com/v1/health

# List your servers
curl -H "Authorization: Bearer $API_JWT_SECRET" \
     https://api.agentflare.com/v1/servers

# Test proxy connectivity
curl -H "Authorization: Bearer $API_JWT_SECRET" \
     -H "X-Target-Server: your-server" \
     https://your-workspace.agentflare.com/proxy/health

# Enable debug headers
curl -H "Authorization: Bearer $API_JWT_SECRET" \
     -H "X-Debug: true" \
     -H "X-Trace: true" \
     https://api.agentflare.com/v1/servers

JavaScript/TypeScript Debugging

// Enable comprehensive logging
const client = new AgentflareClient({
  apiKey: process.env.API_JWT_SECRET,
  debug: true,
  logLevel: 'debug',
  onError: (error) => {
    console.error('Agentflare error:', error);
  },
  onRequest: (request) => {
    console.log('Outgoing request:', request);
  },
  onResponse: (response) => {
    console.log('Incoming response:', response);
  }
});

Python Debugging

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

client = AgentflareClient(
    api_key=os.getenv("API_JWT_SECRET"),
    debug=True,
    log_level="debug"
)

Getting Help

If you’re still experiencing issues after trying these solutions:

Check System Status

See if there are any ongoing service issues

Contact Support

Get help from our technical support team

Community Discord

Ask questions in our community Discord

GitHub Issues

Report bugs or request features

Preventive Measures

Monitor Health

Set up monitoring for your Agentflare integration

Implement Logging

Add comprehensive logging for debugging

Use Error Handling

Implement proper error handling and retries

Regular Testing

Test your integration regularly in staging

For urgent production issues, contact support at support@agentflare.com with your workspace ID and a detailed description of the problem.

Getting Started

Observability

Analytics & Monitoring

Integration

API Reference

Resources

Support

Troubleshooting Guide

Quick Diagnostics

Common Issues & Solutions

Authentication & Authorization

Connection Issues

Tool Call Issues

Performance Issues

Environment-Specific Issues

Development Environment

Production Environment

Debug Tools & Commands

CLI Debugging

JavaScript/TypeScript Debugging

Python Debugging

Getting Help

Check System Status

Contact Support

Community Discord

GitHub Issues

Preventive Measures

Getting Started

Observability

Analytics & Monitoring

Integration

API Reference

Resources

Support

​Quick Diagnostics

​Common Issues & Solutions

​Authentication & Authorization

​Connection Issues

​Tool Call Issues

​Performance Issues

​Environment-Specific Issues

​Development Environment

​Production Environment

​Debug Tools & Commands

​CLI Debugging

​JavaScript/TypeScript Debugging

​Python Debugging

​Getting Help

Check System Status

Contact Support

Community Discord

GitHub Issues

​Preventive Measures

Quick Diagnostics

Common Issues & Solutions

Authentication & Authorization

Connection Issues

Tool Call Issues

Performance Issues

Environment-Specific Issues

Development Environment

Production Environment

Debug Tools & Commands

CLI Debugging

JavaScript/TypeScript Debugging

Python Debugging

Getting Help

Preventive Measures