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

# Troubleshooting

> Common issues, diagnostic commands, and solutions for Arch MCP Server.

## Quick Diagnostics

Run these commands to quickly diagnose issues:

<Tabs>
  <Tab title="Check Installation">
    **Verify all components are installed correctly:**

    ```bash theme={null}
    # Check uv/uvx installation
    uv --version
    uvx --version

    # Check Python version (need 3.11+)
    python --version
    python3 --version

    # Test arch-ops-server directly
    echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx arch-ops-server

    # Check if server can be found
    which arch-ops-server
    uvx --help arch-ops-server
    ```

    <Check>
      **Expected:** All version commands return valid versions, server responds with tools list
    </Check>
  </Tab>

  <Tab title="Check Connectivity">
    **Test network access to Arch services:**

    ```bash theme={null}
    # Test Arch Wiki access
    curl -I https://wiki.archlinux.org

    # Test AUR access
    curl -I https://aur.archlinux.org

    # Test AUR RPC API
    curl "https://aur.archlinux.org/rpc?v=5&type=info&arg=yay"

    # Check general connectivity
    ping -c 3 archlinux.org

    # Test DNS resolution
    nslookup wiki.archlinux.org
    ```

    <Check>
      **Expected:** All services return 200 OK or 301/302 redirects
    </Check>
  </Tab>

  <Tab title="Check Client Logs">
    **View MCP client logs for errors:**

    ```bash theme={null}
    # Claude Desktop (macOS)
    tail -f ~/Library/Logs/Claude/mcp*.log

    # Claude Desktop (Linux)
    tail -f ~/.config/Claude/logs/mcp*.log

    # Cursor (macOS/Linux)
    tail -f ~/.cursor/logs/mcp*.log

    # VS Code - Check Output panel (View → Output → MCP)

    # Filter for errors only
    grep -i error ~/.config/Claude/logs/mcp*.log
    ```

    <Info>
      Look for error messages containing "arch-ops", "spawn", or "ENOENT"
    </Info>
  </Tab>

  <Tab title="Check Configuration">
    **Verify MCP client configuration:**

    ```bash theme={null}
    # Claude Desktop (macOS)
    cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

    # Claude Desktop (Linux)
    cat ~/.config/Claude/claude_desktop_config.json

    # Cursor
    cat ~/.cursor/mcp.json

    # Validate JSON syntax
    python -m json.tool < claude_desktop_config.json

    # Check file permissions
    ls -la ~/.config/Claude/claude_desktop_config.json
    ```

    <Warning>
      Common issues: trailing commas in JSON, wrong quotes, missing braces
    </Warning>
  </Tab>
</Tabs>

***

## Verify Installation

After installing and configuring the Arch MCP Server:

<Steps>
  <Step title="Check client settings">
    Go to settings tab and look for MCP tools icon in your client.

    <Info>
      **Location varies by client:**

      * Claude Desktop: Settings → Features → Model Context Protocol
      * Cursor: Settings → MCP Servers
      * VS Code: MCP extension sidebar
    </Info>
  </Step>

  <Step title="Find arch-ops server">
    You should see "arch-ops" listed as a connected MCP server.

    <Check>
      **Status should be:** Connected (green indicator)
    </Check>

    <Warning>
      If status shows "Disconnected" (red), see troubleshooting below.
    </Warning>
  </Step>

  <Step title="Test a simple query">
    Try a basic query to verify the server responds:

    ```
    Search the Arch Wiki for 'installation guide'
    ```

    <Check>
      **Expected:** Results from Arch Wiki with titles and links
    </Check>
  </Step>

  <Step title="Test a tool">
    Try a specific tool to verify functionality:

    ```
    Use search_aur to find packages matching "neofetch"
    ```

    <Check>
      **Expected:** List of AUR packages with vote counts
    </Check>
  </Step>
</Steps>

## Common Installation Issues

<AccordionGroup>
  <Accordion title="Server shows as disconnected">
    1. Verify uvx is installed: `uvx --version`
    2. Check Python version: `python --version` (need 3.11+)
    3. Reinstall: `uvx --reinstall arch-ops-server`
    4. Restart your MCP client
  </Accordion>

  <Accordion title="arch-ops doesn't appear">
    1. Check config file has valid JSON (no trailing commas)
    2. Verify file location is correct for your client
    3. Completely quit and restart the client (not just reload)
  </Accordion>
</AccordionGroup>

## Server Won't Start

<AccordionGroup>
  <Accordion title="uvx not found" icon="terminal">
    **Error:** `command not found: uvx` or permission errors

    **Diagnosis:**

    ```bash theme={null}
    which uvx
    which uv
    echo $PATH | grep -o "[^:]*bin"
    ```

    **Solutions:**

    1. **Install uv/uvx:**
       ```bash theme={null}
       # Arch Linux
       sudo pacman -S uv

       # Homebrew
       brew install uv

       # pip
       pip install uv

       # Direct install
       curl -LsSf https://astral.sh/uv/install.sh | sh
       ```

    2. **Add to PATH:**
       ```bash theme={null}
       # Add to ~/.bashrc or ~/.zshrc
       export PATH="$HOME/.local/bin:$PATH"

       # Reload shell
       source ~/.bashrc  # or ~/.zshrc
       ```

    3. **Verify installation:**
       ```bash theme={null}
       uvx --version
       which uvx
       ```

    <Tip>
      The uv installer automatically adds to PATH, but you may need to restart your terminal.
    </Tip>
  </Accordion>

  <Accordion title="Python version error" icon="python">
    **Error:** `Python 3.11+ required`

    **Check current version:**

    ```bash theme={null}
    python --version
    python3 --version
    python3.11 --version
    ```

    **Install Python 3.11+:**

    <CodeGroup>
      ```bash Arch Linux theme={null}
      sudo pacman -S python
      ```

      ```bash Ubuntu/Debian theme={null}
      sudo apt update
      sudo apt install python3.11
      ```

      ```bash macOS theme={null}
      brew install python@3.11
      ```

      ```bash From Source theme={null}
      # Download from python.org and compile
      wget https://www.python.org/ftp/python/3.11.0/Python-3.11.0.tgz
      tar -xf Python-3.11.0.tgz
      cd Python-3.11.0
      ./configure && make && sudo make install
      ```
    </CodeGroup>

    **Force specific Python version:**

    ```bash theme={null}
    uvx --python python3.11 arch-ops-server
    ```
  </Accordion>

  <Accordion title="Missing dependencies" icon="box">
    **Error:** `ModuleNotFoundError` or package installation fails

    **Common missing modules:**

    * `httpx` - HTTP client library
    * `beautifulsoup4` - HTML parsing
    * `markdownify` - HTML to Markdown conversion
    * `mcp` - MCP SDK

    **Solutions:**

    1. **Reinstall completely:**
       ```bash theme={null}
       uvx --reinstall arch-ops-server
       ```

    2. **Upgrade to latest version:**
       ```bash theme={null}
       uvx --upgrade arch-ops-server
       ```

    3. **Clear uv cache:**
       ```bash theme={null}
       uv cache clean
       uvx --reinstall arch-ops-server
       ```

    4. **Manual installation:**
       ```bash theme={null}
       uv pip install arch-ops-server
       arch-ops-server
       ```

    <Warning>
      If issues persist, check if you have conflicting Python package managers (pip, conda, pipx).
    </Warning>
  </Accordion>

  <Accordion title="MCP server doesn't connect" icon="plug">
    **Error:** Server shows in tools but says "disconnected"

    **Diagnosis steps:**

    1. **Test server directly:**
       ```bash theme={null}
       # Should output JSON-RPC response
       echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx arch-ops-server
       ```

    2. **Check client logs:**
       ```bash theme={null}
       # macOS
       tail -n 50 ~/Library/Logs/Claude/mcp*.log | grep arch-ops

       # Linux
       tail -n 50 ~/.config/Claude/logs/mcp*.log | grep arch-ops
       ```

    3. **Verify configuration:**
       ```bash theme={null}
       # Check JSON syntax
       python -m json.tool < ~/.config/Claude/claude_desktop_config.json
       ```

    **Common causes:**

    * Syntax error in config file
    * Wrong command path in config
    * Server crashes on startup
    * Permission issues

    **Solutions:**

    * Fix JSON syntax errors (trailing commas, quotes)
    * Use full path: `"/usr/local/bin/uvx"` instead of `"uvx"`
    * Restart client completely (quit and relaunch)
    * Check client logs for specific error messages

    <Info>
      **Expected log output:** `"arch-ops server connected successfully"`
    </Info>
  </Accordion>
</AccordionGroup>

## Tools Return Errors

<Accordion title="checkupdates not found">
  **Error:** `command 'checkupdates' not found`

  **Solution:**
  This is Arch-only and requires `pacman-contrib`:

  ```bash theme={null}
  sudo pacman -S pacman-contrib
  ```

  On non-Arch systems, this tool is not available.
</Accordion>

<Accordion title="Timeout errors">
  **Error:** `TimeoutError` or `request timed out`

  **Solution:**

  1. Check internet connection: `ping google.com`
  2. Try a simpler query first
  3. Verify Arch Wiki and AUR are accessible:
     * Wiki: `xh https://wiki.archlinux.org/api.php`
     * AUR: `xh https://aur.archlinux.org/rpc`
  4. Increase timeout if needed (requires code change)
</Accordion>

<Accordion title="404 from AUR">
  **Error:** `AUR package not found` or HTTP 404

  **Solution:**

  1. Double-check package name spelling
  2. Try searching instead: `Search AUR for 'package-name'`
  3. The AUR might be temporarily down (rare)
  4. Try again in a few minutes
</Accordion>

<Accordion title="Rate limit errors (429)">
  **Error:** `Too many requests` or HTTP 429

  **Solution:**

  * AUR has rate limiting
  * Wait a few minutes before retrying
  * Don't spam requests
  * Share your use case (it's reasonable)
</Accordion>

## Platform-Specific Issues

### On Non-Arch Systems

| Feature               | Status          | Workaround                              |
| --------------------- | --------------- | --------------------------------------- |
| Wiki search & reading | ✅ Full          | Works perfectly                         |
| AUR search & PKGBUILD | ✅ Full          | Works perfectly                         |
| Official package info | ⚠️ Remote API   | Uses online API instead of local pacman |
| Update checking       | ❌ Not available | Requires Arch Linux                     |

### On Arch Linux

All features available. If something isn't working:

1. **Check system is updated:** `sudo pacman -Syu`
2. **Verify dependencies:** `which pacman checkupdates yay paru`
3. **Test locally:** `pacman -Si python` (should work)

## Configuration Issues

<Accordion title="Config syntax error">
  **Error:** `JSON parse error` or `invalid configuration`

  **Solution:**

  1. Validate JSON: Use `jq` or an online JSON validator
  2. Check for trailing commas
  3. Ensure proper JSON formatting
  4. Example valid config:

  ```json theme={null}
  {
    "mcpServers": {
      "arch-ops": {
        "command": "uvx",
        "args": ["arch-ops-server"]
      }
    }
  }
  ```
</Accordion>

<Accordion title="Config not loading">
  **Error:** MCP server doesn't appear in client

  **Solution:**

  1. Restart your MCP client completely
  2. Check config file location:
     * Claude: `~/.config/Claude/claude_desktop_config.json`
     * Cursor: `~/.cursor/mcp_config.json`
  3. Verify file has valid JSON
  4. Clear client cache if available
</Accordion>

## Getting Help

### Debug Commands

```bash theme={null}
# Test server directly (for debugging)
uvx arch-ops-server

# Check uvx installation
uvx --version

# Reinstall if needed
uvx --reinstall arch-ops-server

# View recent logs
journalctl -xe  # system logs
tail -f ~/.config/Claude/logs  # Claude logs (if available)
```

### Resources

* **Arch Wiki Issues:** Check [Arch Wiki](https://wiki.archlinux.org/)
* **AUR Issues:** Check [AUR](https://aur.archlinux.org/)
* **MCP Protocol:** Review [MCP Docs](https://modelcontextprotocol.io/)
* **Bug Reports:** Open an issue on GitHub
* **Feature Requests:** GitHub discussions

***

**Still stuck?** Check the server logs, verify your config is correct, and ensure all prerequisites are installed.