Troubleshooting FAQ¶

Common issues and solutions for the F5XC API MCP Server.

Installation Issues¶

"npx: command not found"¶

Node.js is not installed or not in PATH.

Solution:

# Install Node.js
# macOS
brew install node

# Check version
node --version  # Should be 24+
npx --version

"Package not found"¶

npx cache might be stale.

Solution:

# Clear cache
npx clear-npx-cache

# Try with force flag
npx -y @robinmordasiewicz/f5xc-api-mcp

Docker "image not found"¶

Solution:

# Pull latest image
docker pull ghcr.io/robinmordasiewicz/f5xc-api-mcp:latest

# Or use Docker Hub
docker pull robinmordasiewicz/f5xc-api-mcp:latest

Configuration Issues¶

"MCP server not loading"¶

Claude Desktop or other clients can't connect to the server.

Solutions:

1. Validate JSON configuration:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

1. Check file location matches your OS
2. Restart the application completely
3. Check for syntax errors (trailing commas, missing quotes)

"Environment variables not set"¶

Solutions:

1. For MCP config, use env block:

{
  "env": {
    "F5XC_API_URL": "https://..."
  }
}

1. For shell, export variables:

export F5XC_API_URL="https://..."

1. Verify variables are set:

echo $F5XC_API_URL

Authentication Issues¶

"Authentication failed"¶

API token or certificate is invalid.

Solutions:

1. Token expired: Generate new token in F5XC Console
2. Wrong URL: Check URL format:

https://your-tenant.console.ves.volterra.io

1. Test credentials:

curl -H "Authorization: APIToken $F5XC_API_TOKEN" \
  "$F5XC_API_URL/web/namespaces"

"Certificate error"¶

P12 certificate issues.

Solutions:

1. Use absolute path:

F5XC_P12_BUNDLE="/Users/username/certs/f5xc.p12"  # Correct
F5XC_P12_BUNDLE="./f5xc.p12"  # Wrong

1. Check password: Verify password is correct
2. Check expiration: Certificates expire - regenerate if needed

"Unauthorized"¶

Credentials valid but insufficient permissions.

Solutions:

1. Check namespace access rights
2. Verify service account permissions
3. Contact F5XC administrator

Tool Execution Issues¶

"Tool not found"¶

MCP client can't find F5XC tools.

Solutions:

1. Verify server is running:

npx @robinmordasiewicz/f5xc-api-mcp

1. Check tool name spelling
2. Restart AI assistant

"Validation error"¶

Input parameters don't match schema.

Solutions:

1. Check required parameters
2. Verify data types (string vs number)
3. Use documentation mode to see schema:

   "Show the schema for f5xc-api-waap-http-loadbalancer-create"

"API error: 400 Bad Request"¶

Invalid API request.

Solutions:

1. Check resource name format (alphanumeric, hyphens)
2. Verify namespace exists
3. Check for missing required fields

"API error: 404 Not Found"¶

Resource doesn't exist.

Solutions:

1. Verify resource name and namespace
2. List resources to confirm:

   "List all HTTP load balancers in production namespace"

"API error: 409 Conflict"¶

Resource already exists or conflicting state.

Solutions:

1. Check if resource already exists
2. Wait for pending operations to complete
3. Use update instead of create

Performance Issues¶

"Slow responses"¶

Solutions:

1. Check network connectivity to F5XC
2. Reduce request scope (filter by namespace)
3. Use specific get vs list operations

"Timeout errors"¶

Solutions:

1. Check F5XC service status
2. Verify network allows outbound HTTPS
3. Try simpler operations first

Documentation Mode Issues¶

"Only getting documentation, not executing"¶

Server is in documentation mode (no credentials).

Solution:

Set authentication environment variables:

{
  "env": {
    "F5XC_API_URL": "https://your-tenant.console.ves.volterra.io",
    "F5XC_API_TOKEN": "your-token"
  }
}

"Want documentation but getting execution"¶

Solution:

Remove credentials to use documentation-only mode. This is useful when you want to explore the API without executing operations.

Common Error Messages¶

Getting Help¶

Logs¶

Enable debug logging:

{
  "env": {
    "LOG_LEVEL": "debug"
  }
}

Logs go to stderr (visible in terminal or application logs).

Reporting Issues¶

1. Check existing issues: GitHub Issues
2. Include:
3. Error message
4. Configuration (redact credentials)
5. Steps to reproduce
6. Node.js version: node --version
7. OS and version

Support Channels¶

• GitHub Issues: Bug reports and feature requests
• F5XC Documentation: docs.cloud.f5.com
• F5 Support: For F5XC platform issues