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

# Troubleshooting

> Resolve common issues and errors with WISTX configuration, authentication, and usage

Find solutions to frequently encountered problems with WISTX MCP server, API connections, and tool integrations.

## MCP Server Issues

### MCP Server Not Starting

**Symptoms:**

* MCP server fails to start
* Error messages about missing dependencies
* Connection errors in your coding agent
* "Command not found" errors

**Solutions:**

<AccordionGroup>
  <Accordion title="Check Python Version">
    WISTX requires Python 3.11 or higher. Verify your Python version:

    ```bash theme={null}
    python --version
    # or
    python3 --version
    ```

    If you need to upgrade:

    * **macOS**: `brew install python@3.11` or download from [python.org](https://www.python.org/downloads/)
    * **Linux**: Use your package manager (e.g., `sudo apt install python3.11`)
    * **Windows**: Download from [python.org](https://www.python.org/downloads/)

    <Warning>
      Python 3.8, 3.9, and 3.10 are not supported. You must use Python 3.11 or higher.
    </Warning>
  </Accordion>

  <Accordion title="Check pipx/uvx Installation">
    Verify pipx or uvx is installed and working:

    ```bash theme={null}
    # Check pipx
    pipx --version

    # Check uvx (if using uvx)
    uvx --version
    ```

    If not installed:

    * **pipx**: `pip install --user pipx && pipx ensurepath`
    * **uvx**: Install via [uv](https://github.com/astral-sh/uv) - `curl -LsSf https://astral.sh/uv/install.sh | sh`
  </Accordion>

  <Accordion title="Reinstall WISTX MCP">
    Try reinstalling the package:

    ```bash theme={null}
    # Using pipx (recommended)
    pipx uninstall wistx-mcp
    pipx install wistx-mcp

    # Using uvx
    # uvx doesn't require pre-installation, but you can clear cache
    rm -rf ~/.cache/uvx
    ```

    Verify installation:

    ```bash theme={null}
    pipx run wistx-mcp --help
    ```
  </Accordion>

  <Accordion title="Clear pipx Cache (Stale Version Issues)">
    If you see errors from an old version after updating, pipx may be using a cached version.

    **Symptoms:**

    * Errors mention files or imports that should have been fixed
    * Tool count doesn't match expected (e.g., 20 tools instead of 21)

    **Solution - Clear ALL pipx caches:**

    ```bash theme={null}
    # Clear pipx run cache
    rm -rf ~/.local/pipx/.cache/*

    # Also clear pip's HTTP and wheel cache (used during install)
    rm -rf ~/.cache/pip/
    rm -rf ~/Library/Caches/pip/  # macOS specific

    # Reinstall fresh
    pipx uninstall wistx-mcp 2>/dev/null || true
    pipx install wistx-mcp --force
    ```

    **Verify the correct version is installed:**

    ```bash theme={null}
    # Check installed version
    pipx list | grep wistx-mcp

    # Check the import in user_indexing.py is correct
    grep "normalize_repo_url" ~/.local/pipx/venvs/wistx-mcp/lib/python*/site-packages/wistx_mcp/tools/user_indexing.py
    # Should show: from wistx_mcp.tools.lib.repo_normalizer import normalize_repo_url
    ```

    <Warning>
      After clearing cache, **restart your coding agent completely** (Cmd+Q on macOS). The MCP server process may still have the old code loaded in memory.
    </Warning>
  </Accordion>

  <Accordion title="Check Configuration File Syntax">
    Verify your MCP configuration file syntax is valid JSON:

    ```json theme={null}
    {
      "mcpServers": {
        "wistx": {
          "command": "pipx",
          "args": ["run", "--no-cache", "wistx-mcp"],
          "env": {
            "WISTX_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    Common issues:

    * Missing commas between properties
    * Unclosed brackets or braces
    * Trailing commas (not allowed in JSON)
    * Incorrect environment variable names (should be `WISTX_API_KEY`, not `API_KEY`)
    * Quotes around environment variable values (not needed)

    Validate JSON syntax:

    ```bash theme={null}
    # macOS/Linux
    python3 -m json.tool ~/.cursor/mcp.json

    # Or use online JSON validator
    ```
  </Accordion>

  <Accordion title="Check API Key">
    Ensure your API key is correct and active:

    1. Log in to [wistx.ai/api-key](https://wistx.ai/api-key)
    2. Navigate to **API Keys** section
    3. Verify the key is active (not revoked or expired)
    4. Copy the key again and update your configuration

    <Warning>
      * Make sure there are no extra spaces or quotes around the API key in your configuration
      * The API key should be a string value, not wrapped in quotes in the JSON
      * Environment variable names are case-sensitive: `WISTX_API_KEY` not `wistx_api_key`
    </Warning>

    Test your API key:

    ```bash theme={null}
    curl -X POST https://api.wistx.ai/v1/compliance/requirements \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"resource_types": ["RDS"], "standards": ["PCI-DSS"]}'
    ```
  </Accordion>

  <Accordion title="Check MCP Client Configuration Path">
    Verify you're editing the correct configuration file for your coding agent:

    * **Cursor**: `~/.cursor/mcp.json` (macOS/Linux) or `%APPDATA%\Cursor\mcp.json` (Windows)
    * **Windsurf**: `~/.windsurf/mcp.json` (macOS/Linux) or `%APPDATA%\Windsurf\mcp.json` (Windows)
    * **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
    * **VS Code**: `~/.config/Code/User/mcp.json` (macOS/Linux) or `%APPDATA%\Code\User\mcp.json` (Windows)
    * **Continue.dev**: `~/.continue/config.json`

    <Info>
      Some clients may require creating the directory if it doesn't exist.
    </Info>
  </Accordion>
</AccordionGroup>

### MCP Tools Not Available

**Symptoms:**

* Tools don't appear in your coding agent
* "Tool not found" errors
* Empty tool list
* "Unknown tool" errors

**Solutions:**

<AccordionGroup>
  <Accordion title="Restart Your Coding Agent">
    After configuring WISTX MCP, you must completely restart your coding agent:

    * **Cursor**: Quit completely (Cmd+Q on macOS, Alt+F4 on Windows) and reopen
    * **Claude Desktop**: Quit completely and reopen
    * **VS Code**: Reload the window (Cmd/Ctrl + Shift + P → "Developer: Reload Window")
    * **Windsurf**: Restart Windsurf completely
    * **Continue.dev**: Restart Continue.dev extension
    * **Gemini CLI**: Restart the CLI session

    <Warning>
      Simply closing and reopening a window may not be enough. Ensure the application process is fully terminated.
    </Warning>
  </Accordion>

  <Accordion title="Check MCP Server Logs">
    Check logs for errors:

    * **Cursor**: Check `~/.cursor/logs/` or use Cursor's built-in log viewer
    * **Claude Desktop**: Check `~/Library/Application Support/Claude/logs/` (macOS) or `%APPDATA%\Claude\logs\` (Windows)
    * **VS Code**: Check Output panel → Select "MCP Server" from dropdown
    * **Windsurf**: Check `~/.windsurf/logs/`

    Look for errors like:

    * `ValueError: api_key is required`
    * `RuntimeError: Failed to start MCP server`
    * `ConnectionError: Network connection failed`
  </Accordion>

  <Accordion title="Verify API Key Authentication">
    Test your API key directly:

    ```bash theme={null}
    curl -X POST https://api.wistx.ai/v1/compliance/requirements \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"resource_types": ["RDS"], "standards": ["PCI-DSS"]}'
    ```

    Expected response: JSON with compliance requirements

    If you get `401 Unauthorized`:

    * Your API key is invalid or expired
    * Check the key in [wistx.ai/api-key](https://wistx.ai/api-key)
    * Regenerate if needed

    If you get `429 Too Many Requests`:

    * You've exceeded your rate limit
    * Check your plan limits
    * Wait or upgrade your plan
  </Accordion>

  <Accordion title="Test MCP Server Manually">
    Test if the MCP server can start manually:

    ```bash theme={null}
    # Using pipx
    pipx run wistx-mcp

    # Using uvx
    uvx wistx-mcp
    ```

    If it starts successfully, you should see log output. Press Ctrl+C to stop.

    If it fails:

    * Check Python version (must be 3.11+)
    * Check pipx/uvx installation
    * Check network connectivity
  </Accordion>

  <Accordion title="Check Tool Name Format">
    Ensure you're using the correct tool names. All WISTX tools start with `wistx_`:

    * `wistx_get_compliance_requirements` ✓
    * `wistx_calculate_infrastructure_cost` ✓
    * `wistx_search_code` ✓ (unified code search)
    * `wistx_infrastructure` ✓ (unified infrastructure)
    * `wistx_context` ✓ (unified context management)
    * `wistx_index` ✓ (unified indexing)
    * `wistx_research` ✓ (unified research)
    * `wistx_packages` ✓ (unified packages)
    * `get_compliance_requirements` ✗ (missing prefix)

    If your coding agent shows "Unknown tool" errors, verify the tool name matches exactly.
  </Accordion>
</AccordionGroup>

### Expected Startup Warnings (Not Errors)

Some warnings during MCP server startup are **normal and expected**. These do not affect functionality.

<AccordionGroup>
  <Accordion title="OpenAI API Key Not Configured">
    **Log message:**

    ```
    WARNING - OpenAI API key not configured - AI analysis will be disabled
    ```

    **Impact:** None for normal operation. AI-powered analysis features (like enhanced resource insights) are optional and disabled when the key isn't configured.

    **Resolution:** This is expected behavior. The OpenAI API key is configured on the backend, not required for MCP server operation.
  </Accordion>

  <Accordion title="Authentication Service Temporarily Unavailable (Local Development)">
    **Log message:**

    ```
    ERROR - Error listing MCP resources: Authentication service temporarily unavailable
    ERROR - All connection attempts failed
    ```

    **Impact:** Only affects listing indexed resources in the MCP "Resources" panel (shows `0 resources`). All tools still register and work normally.

    **Why this happens:** When running locally without the backend API, the MCP server cannot authenticate to list your indexed resources. This is expected for local development.

    **What to check:**

    * Tools are registered: Look for `Found 21 tools` in logs ✓
    * All functionality works when connected to production backend

    **Resolution:** No action needed for local development. When connected to production (api.wistx.ai), authentication will succeed.
  </Accordion>

  <Accordion title="MCP SDK Version Warnings">
    **Log messages:**

    ```
    WARNING - MCP SDK version may not support on_initialize decorator
    WARNING - on_initialize handler not registered - SDK will handle initialization automatically
    ```

    **Impact:** None. These are compatibility warnings for different MCP SDK versions.

    **Resolution:** No action needed. The server handles both old and new SDK versions automatically.
  </Accordion>
</AccordionGroup>

## Tool Execution Errors

### Validation Errors (ValueError)

**Symptoms:**

* `ValueError: api_key is required`
* `ValueError: At least one resource type is required`
* `ValueError: Query must be at least 10 characters`
* `ValueError: Invalid search_type`
* Parameter validation errors

**Solutions:**

<AccordionGroup>
  <Accordion title="Missing Required Parameters">
    Most WISTX tools require an `api_key` parameter. Ensure you're passing it:

    ```json theme={null}
    {
      "resource_types": ["RDS"],
      "api_key": "YOUR_API_KEY"
    }
    ```

    Common missing parameters:

    * `wistx_get_compliance_requirements`: Requires `resource_types`
    * `wistx_search_code`: Requires `search_mode` and `query`
    * `wistx_research`: Requires `source` and `query` (min 10 chars for knowledge\_base)
    * `wistx_index`: Requires `action` (and `repo_url` for repository action)

    <Info>
      **Note:** API key is no longer passed as a tool parameter. It's automatically injected from your environment variable (`WISTX_API_KEY`) or MCP initialization.
    </Info>

    Check the [Tools & Features](/integrations/tools-features) page for required parameters for each tool.
  </Accordion>

  <Accordion title="Invalid Parameter Values">
    Check parameter formats and constraints:

    * **Query length**: `wistx_research` with `source="knowledge_base"` requires queries of at least 10 characters
    * **Search mode**: `wistx_search_code` accepts `"semantic"`, `"regex"`, or `"examples"`
    * **Research source**: `wistx_research` accepts `"knowledge_base"`, `"web"`, `"security"`, or `"all"`
    * **Severity**: Must be one of `"CRITICAL"`, `"HIGH"`, `"MEDIUM"`, `"LOW"` (case-sensitive)
    * **Resource types**: Must be an array, not a string
    * **Cloud provider**: Must be `"aws"`, `"gcp"`, or `"azure"` (lowercase)

    Example of correct format:

    ```json theme={null}
    {
      "resource_types": ["RDS", "S3"],
      "standards": ["PCI-DSS", "HIPAA"],
      "severity": "HIGH",
      "api_key": "YOUR_API_KEY"
    }
    ```
  </Accordion>

  <Accordion title="Regex Search Errors">
    For `wistx_search_code` with `search_mode="regex"`, you must provide either `pattern` OR `template`:

    ```json theme={null}
    {
      "pattern": "api_key.*=.*['\"](.*)['\"]",
      "api_key": "YOUR_API_KEY"
    }
    ```

    OR

    ```json theme={null}
    {
      "template": "api_key",
      "api_key": "YOUR_API_KEY"
    }
    ```

    Common errors:

    * Providing both `pattern` and `template` (use only one)
    * Pattern exceeds 10,000 characters
    * Invalid regex syntax
  </Accordion>
</AccordionGroup>

### Runtime Errors

**Symptoms:**

* `RuntimeError: Rate limit exceeded`
* `RuntimeError: Server error: 500`
* `RuntimeError: HTTP error: 404`
* `RuntimeError: Failed to start MCP server`

**Solutions:**

<AccordionGroup>
  <Accordion title="Rate Limit Exceeded">
    If you see `RuntimeError: Rate limit exceeded`:

    1. Check your current usage in [wistx.ai/api-key](https://wistx.ai/api-key) dashboard
    2. Verify your plan limits:

    * **Professional**: 2,000 queries/month
    * **Team**: 10,000 queries/month
    * **Enterprise**: Unlimited queries

    3. Wait for the rate limit to reset (monthly)
    4. Upgrade your plan if needed

    <Info>
      Rate limits reset monthly based on your billing cycle.
    </Info>
  </Accordion>

  <Accordion title="Server Errors (5xx)">
    If you see `RuntimeError: Server error: 500` or similar:

    1. Check [status.wistx.ai](https://status.wistx.ai) for service status
    2. Wait a few minutes and retry
    3. If the issue persists, contact support with:
       * Error message
       * Tool name
       * Timestamp
       * Request details
  </Accordion>

  <Accordion title="Resource Not Found (404)">
    If you see `RuntimeError: HTTP error: 404`:

    * Verify the repository URL is correct (for indexing tools)
    * Check if the resource exists
    * Ensure you have access to the resource
    * For private repositories, verify GitHub OAuth is connected
  </Accordion>
</AccordionGroup>

### Connection and Timeout Errors

**Symptoms:**

* `ConnectionError: Network connection failed`
* `TimeoutError: Request timeout`
* Slow responses
* Intermittent failures

**Solutions:**

<AccordionGroup>
  <Accordion title="Network Connectivity">
    Verify your internet connection:

    ```bash theme={null}
    # Test connectivity to WISTX API
    curl -I https://api.wistx.ai/health

    # Test DNS resolution
    nslookup api.wistx.ai

    # Test with ping
    ping api.wistx.ai
    ```

    Expected: HTTP 200 response from health endpoint
  </Accordion>

  <Accordion title="Firewall/Proxy Issues">
    Ensure firewall/proxy allows connections to:

    * `api.wistx.ai` (port 443, HTTPS)
    * `app.wistx.ai` (port 443, HTTPS)

    If behind a corporate firewall:

    1. Contact your IT department
    2. Request whitelist for `*.wistx.ai` domains
    3. Provide firewall rules if needed

    For proxy configuration, set environment variables:

    ```bash theme={null}
    export HTTP_PROXY=http://proxy.example.com:8080
    export HTTPS_PROXY=http://proxy.example.com:8080
    ```
  </Accordion>

  <Accordion title="Timeout Issues">
    For large operations (indexing, complex searches), timeouts may occur:

    * **Indexing**: Large repositories may take 30+ minutes
    * **Regex search**: Complex patterns on large codebases may timeout
    * **Package search**: Large result sets may take longer

    Solutions:

    * Use `wistx_manage_resources` with `action='status'` to monitor indexing progress
    * Break large searches into smaller queries
    * Use filters to narrow results
    * Increase timeout if using REST API directly
  </Accordion>
</AccordionGroup>

## API Issues

### Authentication Errors

**Symptoms:**

* `401 Unauthorized` errors
* `Invalid API key` messages
* `api_key is required` errors
* Authentication failures

**Solutions:**

<AccordionGroup>
  <Accordion title="Check API Key Format">
    Ensure your API key is in the correct format:

    **For REST API:**

    ```bash theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    **For MCP Tools:**

    ```json theme={null}
    {
      "api_key": "YOUR_API_KEY"
    }
    ```

    Common mistakes:

    * Missing `Bearer` prefix in REST API calls
    * Extra spaces before/after the key
    * Using quotes around the key in JSON (not needed)
    * Including `sk-` or other prefixes (WISTX keys don't have prefixes)
  </Accordion>

  <Accordion title="Verify API Key Status">
    1. Log in to [wistx.ai/api-key](https://wistx.ai/api-key)
    2. Navigate to **API Keys** section
    3. Check if the key is:
       * Active (not revoked)
       * Not expired
       * Has proper permissions
    4. Regenerate if needed (old key will be invalidated)

    <Warning>
      Regenerating an API key will invalidate the old key immediately. Update all configurations.
    </Warning>
  </Accordion>

  <Accordion title="Check API Key in MCP Configuration">
    Verify the API key is correctly set in your MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "wistx": {
          "command": "pipx",
          "args": ["run", "--no-cache", "wistx-mcp"],
          "env": {
            "WISTX_API_KEY": "your-actual-api-key-here"
          }
        }
      }
    }
    ```

    Common issues:

    * Key wrapped in quotes: `"WISTX_API_KEY": "\"key\""` ✗
    * Extra spaces: `"WISTX_API_KEY": " key "` ✗
    * Wrong variable name: `"API_KEY"` instead of `"WISTX_API_KEY"` ✗
  </Accordion>
</AccordionGroup>

### Rate Limit Errors

**Symptoms:**

* `429 Too Many Requests` errors
* `Rate limit exceeded` messages
* Quota exceeded errors

**Solutions:**

<AccordionGroup>
  <Accordion title="Check Your Plan Limits">
    Current plan limits:

    | Plan | Queries/Month | Index Jobs/Month |
    | - | - | - |
    | Professional | 2,000 | 5 |
    | Team | 10,000 | 10 |
    | Enterprise | Unlimited | Unlimited |

    View your current usage in the [dashboard](https://wistx.ai/api-key).

    <Info>
      Queries include all tool calls (compliance, pricing, search, etc.). Index jobs are separate.
    </Info>
  </Accordion>

  <Accordion title="Monitor Usage">
    Check your usage before hitting limits:

    1. Log in to [wistx.ai/api-key](https://wistx.ai/api-key)
    2. Go to **Usage** or **Dashboard**
    3. View:
       * Queries used this month
       * Index jobs used
       * Remaining quota
       * Reset date

    <Warning>
      Rate limits reset monthly based on your billing cycle, not calendar month.
    </Warning>
  </Accordion>

  <Accordion title="Optimize Tool Usage">
    Reduce unnecessary tool calls:

    * Cache results when possible
    * Use filters to narrow searches
    * Batch multiple resource types in a single compliance query
    * Use `wistx_research` with `source="all"` instead of multiple separate searches

    Example of efficient batching:

    ```json theme={null}
    {
      "resource_types": ["RDS", "S3", "EC2"],
      "standards": ["PCI-DSS", "HIPAA"],
      "api_key": "YOUR_API_KEY"
    }
    ```
  </Accordion>

  <Accordion title="Upgrade Your Plan">
    If you consistently hit rate limits:

    1. Visit [wistx.ai/api-key](https://wistx.ai/api-key)
    2. Go to **Billing** or **Plans**
    3. Select a higher plan
    4. Limits increase immediately after upgrade

    <Info>
      Upgrading mid-cycle prorates the cost. Downgrading takes effect at the end of the billing cycle.
    </Info>
  </Accordion>
</AccordionGroup>

## Indexing Issues

### Indexing Fails or Hangs

**Symptoms:**

* Indexing job fails immediately
* Indexing hangs indefinitely
* "Repository access denied" errors
* Slow indexing progress

**Solutions:**

<AccordionGroup>
  <Accordion title="Check Repository Access">
    For private repositories:

    1. **Connect GitHub OAuth** (recommended):
       * Log in to [wistx.ai/api-key](https://wistx.ai/api-key)
       * Go to **Settings** → **Integrations**
       * Connect GitHub account
       * Grant repository access permissions
    2. **Verify repository permissions**:
       * Ensure your GitHub account has access to the repository
       * Check if repository is archived (archived repos may fail)
       * Verify repository visibility (private repos require OAuth)
    3. **Test access manually**:
       ```bash theme={null}
       # If using personal access token
       curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
         https://api.github.com/repos/owner/repo
       ```

    <Info>
      For public repositories, no GitHub token is needed. For private repositories, OAuth is recommended over personal access tokens.
    </Info>
  </Accordion>

  <Accordion title="Check Repository Size and Structure">
    Very large repositories may take longer to index:

    * **Small repos** (\< 100MB): Usually completes in 1-5 minutes
    * **Medium repos** (100MB - 1GB): May take 10-30 minutes
    * **Large repos** (> 1GB): May take 30+ minutes

    Monitor progress:

    ```bash theme={null}
    # Use the check status tool
    {
      "resource_id": "res_abc123",
      "api_key": "YOUR_API_KEY"
    }
    ```

    Optimize indexing:

    * Use `exclude_patterns` to skip unnecessary files:
      ```json theme={null}
      {
        "exclude_patterns": [
          "**/node_modules/**",
          "**/dist/**",
          "**/.git/**",
          "**/vendor/**",
          "**/build/**"
        ]
      }
      ```
    * Use `include_patterns` to focus on DevOps files:
      ```json theme={null}
      {
        "include_patterns": [
          "**/*.tf",
          "**/*.yaml",
          "**/*.yml",
          "**/terraform/**",
          "**/k8s/**"
        ]
      }
      ```
  </Accordion>

  <Accordion title="Check Indexing Quota">
    Verify you haven't exceeded indexing quota:

    * **Professional**: 5 index jobs/month
    * **Team**: 10 index jobs/month
    * **Enterprise**: Unlimited index jobs

    Check your usage:

    1. Log in to [wistx.ai/api-key](https://wistx.ai/api-key)
    2. Go to **Resources** or **Usage**
    3. View indexed resources and remaining quota

    <Warning>
      Deleting and re-indexing the same resource counts as a new index job.
    </Warning>
  </Accordion>

  <Accordion title="Repository URL Format">
    Ensure repository URL is correct:

    **Correct formats:**

    * `https://github.com/owner/repo`
    * `https://github.com/owner/repo.git`

    **Incorrect formats:**

    * `git@github.com:owner/repo.git` (SSH format not supported)
    * `owner/repo` (missing protocol)
    * `github.com/owner/repo` (missing protocol)

    For branch specification:

    ```json theme={null}
    {
      "repo_url": "https://github.com/owner/repo",
      "branch": "main",
      "api_key": "YOUR_API_KEY"
    }
    ```
  </Accordion>

  <Accordion title="Documentation Website Indexing">
    For `wistx_index_resource` with documentation websites:

    Common issues:

    * Website requires authentication (not supported)
    * Website blocks crawlers (check robots.txt)
    * Very large websites (> 10,000 pages may timeout)
    * Dynamic content (JavaScript-rendered content may not be indexed)

    Solutions:

    * Use `include_patterns` to limit scope:
      ```json theme={null}
      {
        "content_url": "https://docs.example.com",
        "include_patterns": ["/docs/", "/api/"],
        "exclude_patterns": ["/admin/", "/private/"]
      }
      ```
    * Index specific sections separately
    * Use PDF/DOCX upload for static documentation
  </Accordion>
</AccordionGroup>

### Indexing Status Issues

**Symptoms:**

* Status stuck on "indexing"
* Status shows "failed" but no error message
* Can't check status

**Solutions:**

<AccordionGroup>
  <Accordion title="Check Resource Status">
    Use `wistx_manage_resources` with `action='status'` to monitor progress:

    ```json theme={null}
    {
      "action": "status",
      "resource_id": "res_abc123",
      "api_key": "YOUR_API_KEY"
    }
    ```

    Status values:

    * `pending`: Job queued, waiting to start
    * `indexing`: Currently processing
    * `completed`: Successfully indexed
    * `failed`: Indexing failed (check error message)

    **Recommended:** Check status at reasonable intervals (every 30-60 seconds) after initiating indexing, or when the user asks about progress.

    <Info>
      Resource ID is returned when you start indexing. Save it to check status later.
    </Info>
  </Accordion>

  <Accordion title="Handle Failed Indexing">
    If indexing fails:

    1. Check the error message in status response
    2. Common causes:
       * Repository access denied (check GitHub OAuth)
       * Repository too large (use exclude\_patterns)
       * Network timeout (retry)
       * Invalid repository URL
    3. Retry indexing with adjusted parameters
    4. Contact support if issue persists
  </Accordion>

  <Accordion title="List All Resources">
    Use `wistx_manage_resources` with `action='list'` to see all indexed resources:

    ```json theme={null}
    {
      "action": "list",
      "api_key": "YOUR_API_KEY"
    }
    ```

    Filter by status:

    ```json theme={null}
    {
      "action": "list",
      "status_filter": "completed",
      "api_key": "YOUR_API_KEY"
    }
    ```

    Filter by resource type:

    ```json theme={null}
    {
      "action": "list",
      "resource_type": "repository",
      "api_key": "YOUR_API_KEY"
    }
    ```
  </Accordion>
</AccordionGroup>

## Search and Query Issues

### No Results Found

**Symptoms:**

* Search returns empty results
* "No matches found" messages
* Expected results not appearing

**Solutions:**

<AccordionGroup>
  <Accordion title="Check Indexed Resources">
    Ensure resources are indexed before searching:

    1. Use `wistx_manage_resources` with `action='list'` to see indexed resources
    2. Verify the repository/documentation you're searching is indexed
    3. Check indexing status is "completed"
    4. Re-index if needed

    <Warning>
      `wistx_search_code` only searches your indexed resources. It won't search unindexed repositories.
    </Warning>
  </Accordion>

  <Accordion title="Broaden Search Query">
    Try broader search terms:

    * Instead of: "RDS encryption configuration"
    * Try: "RDS encryption" or "encryption"

    Use natural language queries:

    ```json theme={null}
    {
      "query": "How do I configure RDS encryption?",
      "api_key": "YOUR_API_KEY"
    }
    ```
  </Accordion>

  <Accordion title="Check Filters">
    Remove restrictive filters:

    * Try without `code_type` filter
    * Try without `cloud_provider` filter
    * Try without `file_types` filter
    * Check `repositories` filter matches indexed repos

    Example without filters:

    ```json theme={null}
    {
      "query": "Terraform RDS configuration",
      "api_key": "YOUR_API_KEY"
    }
    ```
  </Accordion>

  <Accordion title="Use Different Search Tools">
    Try alternative search approaches using the unified `wistx_search_code` tool:

    * **Semantic search**: `wistx_search_code` with `search_mode="semantic"` (natural language)
    * **Pattern search**: `wistx_search_code` with `search_mode="regex"` (exact patterns)
    * **Code examples**: `wistx_search_code` with `search_mode="examples"` (curated examples)
    * **Package search**: `wistx_packages` with `action="search"` (for packages)
    * **Research**: `wistx_research` with `source="knowledge_base"` (general knowledge)
  </Accordion>
</AccordionGroup>

## Getting Help

If you're still experiencing issues:

1. **Check Documentation**:
   * [Installation Guide](/integrations/wistx-mcp)
   * [Tools & Features](/integrations/tools-features)
   * [API Reference](/api-reference/introduction)

2. **Check Service Status**:
   * Visit [status.wistx.ai](https://status.wistx.ai) for service status

3. **Search Existing Issues**:
   * Check [GitHub Issues](https://github.com/WISTXHQ/wistx-model/issues) for similar problems

4. **Contact Support**:
   * Email: [hi@wistx.ai](mailto:hi@wistx.ai)
   * Include:
     * Error messages (full text)
     * Tool name and parameters used
     * Request IDs (from response metadata)
     * Steps to reproduce
     * Your plan type
     * Python version (`python --version`)
     * Coding agent and version

5. **Community**:
   * Join our [Discord community](https://discord.gg/ZVGK5Fv3wT) for real-time support and discussions
   * Visit our [GitHub repository](https://github.com/WISTXHQ/wistx-model) to report issues and contribute
   * Check [GitHub Discussions](https://github.com/WISTXHQ/wistx-model/discussions) for community Q\&A

<Info>
  When contacting support, please include:

  * Complete error messages
  * Tool name and parameters
  * Request IDs (if available)
  * Steps to reproduce the issue
  * Your plan type (Professional/Team/Enterprise)
  * Python version
  * Coding agent name and version
  * MCP configuration (with API key redacted)
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.