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

# Troubleshooting

> Common issues and solutions for Pylee MCP server setup and usage

# Troubleshooting

Having trouble with Pylee? This guide covers the most common issues and their solutions.

<Info>
  **Quick Help**: Most setup issues can be resolved by restarting your application completely and checking your API key. If problems persist, try the solutions below.
</Info>

## Common Issues and Solutions

<AccordionGroup>
  <Accordion title="Pylee MCP Server Not Appearing">
    **Symptoms**: Claude Desktop or other MCP clients don't show Pylee as available

    **Solutions**:

    <Steps>
      <Step title="Verify Configuration File Location">
        Ensure your config file is in the correct location:

        * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
        * **Linux**: `~/.config/Claude/claude_desktop_config.json`
      </Step>

      <Step title="Check JSON Syntax">
        Validate your JSON configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "pylee": {
              "command": "npx",
              "args": ["-y", "@pyleeai/pylee@latest"]
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Application">
        Completely quit and restart Claude Desktop (or your MCP client)
      </Step>

      <Step title="Check Node.js Installation">
        Verify Node.js is installed:

        ```bash theme={null}
        node --version
        npm --version
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Connection Timeout Issues">
    **Symptoms**: MCP server starts but times out when trying to connect

    **Solutions**:

    <Steps>
      <Step title="Check Internet Connection">
        Ensure you have a stable internet connection
      </Step>

      <Step title="Verify Firewall Settings">
        Make sure your firewall isn't blocking the connection:

        * Allow `npx` and `node` through your firewall
        * Check corporate firewall settings if applicable
      </Step>

      <Step title="Test Network Access">
        ```bash theme={null}
        # Test connection to Pylee API
        curl -I https://api.pyleeai.com/health
        ```
      </Step>

      <Step title="Try Alternative Configuration">
        If using `npx` fails, try installing globally:

        ```bash theme={null}
        npm install -g @pyleeai/mcp-server
        ```

        Then update your config to use:

        ```json theme={null}
        {
          "command": "pylee-mcp-server"
        }
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Permission Denied Errors">
    **Symptoms**: Errors about file permissions or access denied

    **Solutions**:

    <Steps>
      <Step title="Check File Permissions">
        Ensure you can read/write the configuration file:

        ```bash theme={null}
        # macOS/Linux
        ls -la "~/Library/Application Support/Claude/"
        # or
        ls -la ~/.config/Claude/
        ```
      </Step>

      <Step title="Create Directory if Missing">
        ```bash theme={null}
        # macOS
        mkdir -p "~/Library/Application Support/Claude"

        # Linux
        mkdir -p ~/.config/Claude
        ```
      </Step>

      <Step title="Fix Ownership (macOS/Linux)">
        ```bash theme={null}
        # macOS
        sudo chown -R $(whoami) "~/Library/Application Support/Claude"

        # Linux  
        sudo chown -R $(whoami) ~/.config/Claude
        ```
      </Step>

      <Step title="Run as Administrator (Windows)">
        Try running your text editor as Administrator when editing the config file
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Node.js or NPM Issues">
    **Symptoms**: Commands not found or version conflicts

    **Solutions**:

    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        # Install Node.js via Homebrew
        brew install node

        # Or use Node Version Manager
        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
        nvm install node
        nvm use node
        ```
      </Tab>

      <Tab title="Windows">
        1. Download Node.js from [nodejs.org](https://nodejs.org)
        2. Run the installer as Administrator
        3. Restart your command prompt/PowerShell
        4. Verify installation:

        ```cmd theme={null}
        node --version
        npm --version
        ```
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        # Ubuntu/Debian
        curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
        sudo apt-get install -y nodejs

        # Fedora
        sudo dnf install nodejs npm

        # Arch Linux
        sudo pacman -S nodejs npm
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Registry Not Loading">
    **Symptoms**: Pylee connects but no registry servers are available

    **Solutions**:

    <Steps>
      <Step title="Check Registry Status">
        1. Log into [Pylee Dashboard](https://app.pyleeai.com/dashboard)
        2. Go to "Active Registries"
        3. Verify your registries are activated
      </Step>

      <Step title="Refresh Registry">
        In your dashboard, click "Refresh" on your active registries
      </Step>

      <Step title="Check Permissions">
        Ensure you have access to the registries you're trying to use
      </Step>

      <Step title="Test with Different Registry">
        Try activating a different registry to isolate the issue
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Platform-Specific Issues

<Tabs>
  <Tab title="macOS">
    ### Common macOS Issues

    **Gatekeeper blocking execution**:

    ```bash theme={null}
    # Allow npx to run
    sudo spctl --master-disable
    # Run your MCP client, then re-enable:
    sudo spctl --master-enable
    ```

    **SIP (System Integrity Protection) issues**:

    * Use Homebrew to install Node.js instead of the system installer
    * Avoid modifying system directories

    **Permission issues with Application Support**:

    ```bash theme={null}
    # Fix permissions
    sudo chown -R $(whoami) "~/Library/Application Support"
    ```
  </Tab>

  <Tab title="Windows">
    ### Common Windows Issues

    **Execution policy restrictions**:

    ```powershell theme={null}
    # Run PowerShell as Administrator
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```

    **Path issues**:

    * Add Node.js to your PATH environment variable
    * Restart command prompt after installing Node.js

    **AppData access issues**:

    * Run text editor as Administrator
    * Check that %APPDATA% environment variable is set correctly
  </Tab>

  <Tab title="Linux">
    ### Common Linux Issues

    **Snap-installed applications**:

    * Snap packages may have restricted file system access
    * Install Node.js via your package manager instead

    **Permission issues**:

    ```bash theme={null}
    # Fix npm permissions
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
    source ~/.bashrc
    ```

    **SELinux restrictions**:

    ```bash theme={null}
    # Temporarily disable SELinux (if applicable)
    sudo setenforce 0
    ```
  </Tab>

  <Tab title="WSL">
    ### Common WSL Issues

    **Mixed Windows/Linux paths**:

    * Keep configuration files in Linux filesystem for better performance
    * Use Linux paths in your configuration

    **Node.js installation**:

    ```bash theme={null}
    # Install via package manager, not Windows installer
    curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
    sudo apt-get install -y nodejs
    ```

    **File system permissions**:

    ```bash theme={null}
    # Ensure proper permissions
    sudo chown -R $(whoami) ~/.config
    ```
  </Tab>
</Tabs>

## Getting Debug Information

If you're still having issues, gather this information before contacting support:

<Steps>
  <Step title="System Information">
    ```bash theme={null}
    # Check versions
    node --version
    npm --version

    # Check OS
    uname -a  # macOS/Linux
    # or
    systeminfo  # Windows
    ```
  </Step>

  <Step title="Configuration File">
    Verify your configuration file exists and has correct content:

    ```bash theme={null}
    # macOS
    cat "~/Library/Application Support/Claude/claude_desktop_config.json"

    # Linux
    cat ~/.config/Claude/claude_desktop_config.json

    # Windows (PowerShell)
    Get-Content "$env:APPDATA\Claude\claude_desktop_config.json"
    ```
  </Step>

  <Step title="Test MCP Server Directly">
    ```bash theme={null}
    # Test if the MCP server starts
    npx @pyleeai/pylee@latest
    ```
  </Step>

  <Step title="Check Network Connectivity">
    ```bash theme={null}
    # Test API connectivity
    curl -v https://api.pyleeai.com/health
    ```
  </Step>
</Steps>

## Still Need Help?

<CardGroup cols={2}>
  <Card title="Contact Support" icon="headset" href="mailto:support@pyleeai.com">
    Email us with your debug information
  </Card>

  <Card title="Community Discord" icon="discord" href="https://discord.gg/pylee">
    Get help from the community
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/pyleeai/mcp-server/issues">
    Report bugs or request features
  </Card>

  <Card title="Documentation" icon="book" href="/get-started/introduction">
    Review the full documentation
  </Card>
</CardGroup>

<Note>
  When contacting support, please include:

  * Your operating system and version
  * Node.js and npm versions
  * Your configuration file (with API key redacted)
  * Any error messages you're seeing
  * Steps you've already tried
</Note>

## Additional Resources

<CardGroup cols={2}>
  <Card title="Getting Started Guide" icon="rocket" href="/get-started/getting-started">
    Review the initial setup process
  </Card>

  <Card title="Registry Activation" icon="database" href="/using-pylee/activating-registry">
    Learn about managing MCP server registries
  </Card>

  <Card title="Configuration Guide" icon="gear" href="/using-pylee/configuration">
    Advanced configuration options
  </Card>

  <Card title="Community Support" icon="users" href="https://discord.gg/pylee">
    Connect with other Pylee users
  </Card>
</CardGroup>

## Reporting Issues

If you can't find a solution to your problem:

1. **Check our GitHub Issues** - Someone may have already reported the same issue
2. **Search the documentation** - Use the search function to find relevant information
3. **Contact support** - Include detailed information about your setup and the issue you're experiencing

<Note>
  When reporting issues, please include your operating system, Node.js version, and any error messages you're seeing. This helps us provide better support.
</Note>