Troubleshooting Guide¶

This guide helps you resolve common issues when installing or using the F5 XC Cloud Status MCP server.

Common Issues Across All Platforms¶

Issue 1: "npx: command not found"¶

Symptoms:

command not found: npx
npm: command not found

Root Cause: Node.js or npm is not properly installed or not in your PATH

Solutions: 1. Install Node.js:

# Check if Node.js is installed
node --version
npm --version

# If not installed, download from https://nodejs.org
# Install version 18.0.0 or higher

Update PATH (if Node.js is installed but not in PATH):

# Find Node.js installation
which node
which npm

# Add to PATH in ~/.bash_profile or ~/.zshrc
export PATH="/usr/local/bin:$PATH"

Reinstall Node.js:

# Using Homebrew (macOS/Linux)
brew install node@18

# Or download from https://nodejs.org

Verification:

node --version  # Should be v18.0.0 or higher
npm --version   # Should be 8.0.0 or higher
npx --version   # Should work without error

Issue 2: "Cannot find module '@robinmordasiewicz/f5xc-cloudstatus-mcp'"¶

Symptoms:

npm ERR! 404 Not Found
error when installing package
Module not found

Root Cause: - Package not found on npm registry - Network connectivity issue - npm cache corrupted

Solutions:

Check npm registry:

# Search for the package
npm search @robinmordasiewicz/f5xc-cloudstatus-mcp

# Or visit: https://www.npmjs.com/package/@robinmordasiewicz/f5xc-cloudstatus-mcp

Clear npm cache:

npm cache clean --force
npm install -g npm@latest  # Update npm

Check internet connection:

# Try downloading a different package
npx -y create-react-app --version

# Or ping npm registry
curl -I https://registry.npmjs.org/

Try alternative package source:

# Use GitHub directly (for development versions)
npm install github:robinmordasiewicz/f5xc-cloudstatus-mcp

Verification:

npm view @robinmordasiewicz/f5xc-cloudstatus-mcp version

Issue 3: "EACCES: permission denied"¶

Symptoms:

EACCES: permission denied
Error: ENOENT: no such file or directory

Root Cause: npm modules directory doesn't have write permissions

Solutions:

Fix npm permissions (recommended):

# Create a directory for global packages
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH in ~/.bash_profile or ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bash_profile  # or ~/.zshrc

Alternative: Change npm default directory:
```
npm config set prefix /usr/local
```

Never use sudo with npm:

# WRONG - never do this
sudo npm install -g package

# RIGHT - fix permissions instead
npm install -g package

Verification:

npm list -g  # Should work without permission errors

Issue 4: "Invalid JSON syntax"¶

Symptoms:

SyntaxError: Unexpected token } in JSON
Invalid JSON configuration

Root Cause: Missing commas, quotes, or brackets in configuration file

Solutions:

Validate JSON syntax:

# For Claude Code
python -m json.tool .mcp.json

# For OpenCode
python -m json.tool ~/.config/opencode/opencode.json

# For Claude Desktop
python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

Common JSON errors:

// WRONG - missing comma
{
  "server": "f5xc",
  "enabled": true     // <- missing comma here
  "debug": false
}

// RIGHT
{
  "server": "f5xc",
  "enabled": true,
  "debug": false
}

Use an editor with JSON validation:

# VS Code automatically validates JSON
code ~/.config/opencode/opencode.json

# Or use vim with syntax checking
vim ~/.config/opencode/opencode.json

Verification:

# After fixing JSON, validate again
python -m json.tool <config-file>
# Should show formatted JSON without errors

Platform-Specific Issues¶

Claude Code Issues¶

Issue: Server not showing up

Solutions: 1. Verify .mcp.json exists:

cat .mcp.json | grep f5xc-cloudstatus

Check JSON syntax:
```
python -m json.tool .mcp.json
```

Verify package can be accessed:

npx -y @robinmordasiewicz/f5xc-cloudstatus-mcp@latest --version

Try using local build:

{
  "mcpServers": {
    "f5xc-cloudstatus": {
      "command": "node",
      "args": ["/path/to/f5xc-cloudstatus-mcp/dist/index.js"]
    }
  }
}

OpenCode Issues¶

Issue: Server not appearing after configuration

Solutions: 1. Verify configuration location:

ls -la ~/.config/opencode/opencode.json
cat ~/.config/opencode/opencode.json | grep f5xc-cloudstatus

Check JSON syntax:

python -m json.tool ~/.config/opencode/opencode.json

Restart OpenCode:

# Kill and restart OpenCode
pkill opencode
opencode

Check MCP configuration structure:

# Should have "mcp" object with server configuration
cat ~/.config/opencode/opencode.json | grep -A 5 '"mcp"'

VS Code Issues¶

Issue: "VS Code version too old"

Solutions: 1. Check VS Code version:

code --version
# Should be 1.96.0 or higher

Update VS Code:

# Using Homebrew (macOS)
brew upgrade visual-studio-code

# Or download latest from https://code.visualstudio.com

Issue: Server not showing in chat

Solutions: 1. Verify configuration was created:

cat ~/.config/Code/User/settings.json | grep f5xc-cloudstatus

Reload VS Code:
Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
Type "Developer: Reload Window"
Press Enter

Use --add-mcp command instead:

code --add-mcp '{"name":"f5xc-cloudstatus","command":"npx","args":["-y","@robinmordasiewicz/f5xc-cloudstatus-mcp@latest"]}'

Check JSON syntax:

python -m json.tool ~/.config/Code/User/settings.json

Claude Desktop Issues¶

Issue: Server not appearing after restart

Solutions: 1. Verify configuration was saved:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | grep f5xc-cloudstatus

Check JSON syntax:

python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

Fully restart Claude Desktop:

# Close completely
pkill -f "Claude" || killall Claude

# Wait 2 seconds
sleep 2

# Relaunch
open -a Claude

Restore from backup if corrupted:

cp ~/Library/Application\ Support/Claude/claude_desktop_config.json.backup ~/Library/Application\ Support/Claude/claude_desktop_config.json

Issue: "It just keeps asking for Node to be installed"

Solutions: 1. Verify Node.js PATH:

which node
which npm

Check Node.js installation:

node --version  # Should be v18.0.0+
npm --version

Update PATH for Claude Desktop: Claude Desktop may need to read your shell profile. Add Node.js to your PATH:
```
# In ~/.zshrc or ~/.bash_profile
export PATH="/usr/local/bin:$PATH"
```

API Connectivity Issues¶

Issue: "F5 Cloud API not responding"

Symptoms:

No response from API
Timeout errors
Empty results

Root Cause: - F5 Cloud API is temporarily unavailable - Network connectivity issue - Incorrect API URL

Solutions:

Check F5 Cloud Status:

# Visit the status page
open https://www.f5cloudstatus.com

Verify network connectivity:

# Test connection to F5 API
curl -I https://www.f5cloudstatus.com/api/v2/overall

# Should return HTTP 200

Check firewall/proxy settings:
Ensure firewall allows outbound HTTPS connections
Check if proxy is interfering with API calls
Wait and retry:
If F5 Cloud is experiencing issues, wait and try again

Performance Issues¶

Issue: Slow response times

Symptoms:

Responses taking > 10 seconds
Timeout errors

Root Cause: - Network latency - F5 Cloud API slow - System resources constrained

Solutions:

Check network speed:

# Test connection
curl -w "@curl-format.txt" -o /dev/null -s https://www.f5cloudstatus.com/api/v2/overall

Check system resources:

# View CPU and memory usage
top -l 1 | head -20

Retry with patience:
F5 Cloud API may have temporary delays
Expected response time is typically < 5 seconds

Getting Help¶

If you can't resolve your issue:

Check Documentation:
Review the platform-specific guide you're using
Check Home for general information
Verify Prerequisites:
Node.js 18.0.0+ installed
npm available
Internet connection working
F5 Cloud API accessible

Gather Diagnostic Information:

# System information
node --version
npm --version
code --version  # (if using VS Code)

# Configuration (sanitized)
cat .mcp.json | head -20  # (if using Claude Code)

# Network test
curl -I https://www.f5cloudstatus.com/api/v2/overall

Report Issues:
GitHub Issues: https://github.com/robinmordasiewicz/f5xc-cloudstatus-mcp/issues
Include diagnostic information from above
Include the exact error message and steps to reproduce

Last Updated: January 2026 Version: 1.3.0+ Status Page: https://www.f5cloudstatus.com