Skip to main content

​
Troubleshooting Guide

Quick fixes for common FlowMCP issues.

​
Common Issues

​
Schema Validation Errors

“namespace must contain only letters” 
// ❌ Wrong
namespace: "github-api"  // No hyphens
namespace: "api2"        // No numbers

// ✅ Correct
namespace: "github"
“flowMCP version invalid” 
// ❌ Wrong
flowMCP: "1.2"      // Missing patch version
flowMCP: "v1.2.2"   // No 'v' prefix

// ✅ Correct
flowMCP: "1.2.2"
“parameters must be single-line” 
// ❌ Wrong - Multi-line
parameters: [
  {
    position: {
      location: "insert",
      key: "id",
      value: "{{USER_PARAM}}"
    }
  }
]

// ✅ Correct - Single line
parameters: [
  { position: { key: "id", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["length(24)"] } }
]

​
Server Startup Issues

Port already in use 
# Check what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use different port
PORT=3001 node server.mjs
Missing environment variables 
# Check required vars
node -e "console.log(process.env.GITHUB_TOKEN)"

# Set variables
export GITHUB_TOKEN=ghp_xxxxx
export API_KEY=xxxxx

# Or use .env file
npm install dotenv
Schema not found 
// Check file path
import { readFileSync } from 'fs'
import { resolve } from 'path'

const schemaPath = resolve('./schemas/github.mjs')
console.log('Looking for:', schemaPath)

​
API Request Failures

401 Unauthorized
  • Check API key format
  • Verify token hasn’t expired
  • Ensure correct header format
// Common auth patterns
headers: {
  "Authorization": "Bearer {{TOKEN}}",      // Bearer token
  "X-API-Key": "{{API_KEY}}",              // API key header
  "Authorization": "token {{GITHUB_TOKEN}}" // GitHub format
}
429 Rate Limited
  • Implement exponential backoff in your application
  • Check API documentation for rate limits
  • Consider using multiple API keys if available
Network timeout
  • Check network connectivity
  • Verify API endpoint is responding
  • Consider increasing request timeout in your HTTP client

​
Claude Desktop Integration

MCP server not showing
  1. Check config location:
    • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Verify config format: 
{
  "mcpServers": {
    "flowmcp": {
      "command": "node",
      "args": ["/absolute/path/to/server.mjs"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}
  1. Restart Claude Desktop completely
Tools not appearing
  • Check server logs for errors
  • Verify schemas are valid with FlowMCP.validateSchema()
  • Ensure FlowMCP.activateServerTools() is called correctly

​
Performance Issues

High memory usage 
// Limit schemas loaded
const { filteredArrayOfSchemas } = FlowMCP.filterArrayOfSchemas({
  arrayOfSchemas: allSchemas,
  includeNamespaces: ['github']  // Only needed APIs
})

// Only activate filtered schemas
filteredArrayOfSchemas.forEach(schema => {
  FlowMCP.activateServerTools({ server, schema, serverParams })
})
Slow startup
  • Validate schemas once during development, not at runtime
  • Use schema filtering to reduce the number of activated schemas
  • Consider lazy loading of schemas only when needed

​
Error Messages

​
Schema Errors

ErrorCauseSolution
namespace invalidContains non-lettersUse only a-zA-Z
route missing requestMethodIncomplete routeAdd all required fields
parameter missing z validationNo Zod schemaAdd z object to params
serverParams not declaredMissing from requiredServerParamsAdd to array

​
Runtime Errors

ErrorCauseSolution
ECONNREFUSEDServer not runningStart server first
ETIMEDOUTRequest timeoutIncrease timeoutMs
ENOTFOUNDInvalid URLCheck root URL
Invalid JSONMalformed responseCheck API response format

​
Debug Mode

Enable detailed logging: 
// Set debug environment variables
process.env.DEBUG = 'flowmcp:*'
process.env.LOG_LEVEL = 'debug'

// Add logging to your server
import { FlowMCP } from './src/index.mjs'

// Log schema validation
schemas.forEach(schema => {
  const validation = FlowMCP.validateSchema({ schema })
  console.log(`Schema ${schema.namespace}:`, validation.status ? '✅' : '❌')
  if (!validation.status) {
    console.log('Errors:', validation.messages)
  }
})

// Log API requests
const result = await FlowMCP.fetch({ schema, userParams, serverParams, routeName })
console.log('API Result:', { status: result.status, messages: result.messages })

​
Testing Tools

​
Schema Validator

import { FlowMCP } from './src/index.mjs'

function validateAllSchemas(schemas) {
  schemas.forEach(schema => {
    const { status, messages } = FlowMCP.validateSchema({ schema })
    if (!status) {
      console.error(`${schema.namespace} failed:`, messages)
    } else {
      console.log(`✅ ${schema.namespace} valid`)
    }
  })
}

// Usage
validateAllSchemas([githubSchema])

​
API Tester

async function testRoute(schema, routeName, userParams) {
  const result = await FlowMCP.fetch({
    schema,
    routeName,
    userParams,
    serverParams: process.env
  })
  
  console.log('Status:', result.status)
  console.log('Response:', result.dataAsString)
  
  if (!result.status) {
    console.error('Errors:', result.messages)
  }
}

​
Health Check

async function healthCheck(server) {
  try {
    const response = await fetch('http://localhost:3000/health')
    const health = await response.json()
    console.log('Server health:', health)
  } catch (error) {
    console.error('Server down:', error)
  }
}

​
Getting Help

​
Resources

​
Debug Checklist

Before asking for help: ✅ Schema validates without errors
✅ Environment variables are set
✅ Server starts without errors
✅ Test with simple schema first
✅ Check server logs for details
✅ Try example from docs
✅ Update to latest version

​
Report Template

When reporting issues, include: 
**Environment:**
- FlowMCP version: x.x.x
- Node.js version: xx.x.x
- OS: Mac/Windows/Linux

**Schema:**
```javascript
// Minimal schema that reproduces issue
Error: 
// Full error message
Expected behavior: What should happen Actual behavior: What actually happens