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

# Troubleshooting

> Common issues and solutions for Nia

## Common Issues

<AccordionGroup>
  <Accordion title="`nia` command runs wrong version after wizard setup">
    **Problem:** After running `npx nia-wizard@latest`, the `nia` command fails, behaves unexpectedly, or still shows the old local-sync daemon.

    **Cause:** The deprecated `nia-sync` package (installed via `pip` or `uv`) ships a binary also called `nia`. It shadows the new CLI that the wizard installs.

    **Solution:**

    1. Uninstall the old package:

    ```bash theme={null}
    pip uninstall nia-sync   # or: uv pip uninstall nia-sync
    ```

    2. Clear your shell's command cache and verify:

    ```bash theme={null}
    hash -r              # reset shell lookup cache (bash/zsh)
    which nia            # should point to the new CLI, not a pip path
    ```

    On Windows (PowerShell):

    ```powershell theme={null}
    Get-Command nia      # should point to the new CLI, not a pip path
    ```

    3. Re-run the wizard:

    ```bash theme={null}
    npx nia-wizard@latest
    ```
  </Accordion>

  <Accordion title="MCP configuration file doesn't exist">
    **Problem:** The mcp.json file doesn't exist in the expected location.

    **Solution:** You can create the file manually. The mcp.json file should be located at:

    * **macOS (Cursor)**: `~/.cursor/mcp.json`
    * **macOS (Windsurf)**: `~/.windsurf/mcp.json`
    * **macOS (Claude Desktop)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows (Cursor)**: `%APPDATA%\Cursor\mcp.json`
    * **Windows (Windsurf)**: `%APPDATA%\Windsurf\mcp.json`
    * **Windows (Claude Desktop)**: `%APPDATA%\Claude\claude_desktop_config.json`
    * **Linux (Cursor)**: `~/.config/cursor/mcp.json`
    * **Linux (Windsurf)**: `~/.config/windsurf/mcp.json`

    Create the directory if it doesn't exist, then create the mcp.json file with the configuration from the [installation guide](/integrations/installation/mcp).

    Example:

    ```bash theme={null}
    # For Cursor on macOS
    mkdir -p ~/.cursor
    touch ~/.cursor/mcp.json
    ```

    Then add the configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "nia": {
          "command": "pipx",
          "args": ["run", "--no-cache", "nia-mcp-server"],
          "env": {
            "NIA_API_KEY": "YOUR_API_KEY",
            "NIA_API_URL": "https://apigcp.trynia.ai/"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Tools not showing in MCP client">
    **Problem:** After installation, the Nia tools don't appear in your MCP client (Cursor, Claude Desktop, etc.).

    **Solution:** This usually happens when the MCP server isn't installed globally. Make sure you've installed using `pipx` for global installation:

    ```bash theme={null}
    # Install pipx first if you haven't
    pip install pipx

    # Install nia-mcp-server globally
    pipx install nia-mcp-server
    ```

    Why `pipx` is recommended:

    * `pipx` installs packages globally in isolated environments
    * Tools are available system-wide
    * No conflicts with other Python packages
    * Automatic PATH management

    After installing with `pipx`:

    1. Update your MCP configuration to use `pipx run`
    2. Restart your MCP client completely
    3. Check if tools appear in the MCP tools section

    If you previously installed with `pip`, uninstall first:

    ```bash theme={null}
    pip uninstall nia-mcp-server
    pipx install nia-mcp-server
    ```
  </Accordion>

  <Accordion title="&#x22;No API key provided&#x22; error">
    **Problem:** Getting an error that no API key was provided.

    **Solution:**

    1. Ensure you've replaced `YOUR_API_KEY` with your actual API key from [app.trynia.ai](http://app.trynia.ai/)
    2. Check that the environment variable is correctly set in your MCP configuration
    3. Verify there are no typos in the environment variable name `NIA_API_KEY`
    4. Make sure there are no extra spaces or hidden characters in your API key

    Example of correct configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "nia": {
          "command": "pipx",
          "args": ["run", "--no-cache", "nia-mcp-server"],
          "env": {
            "NIA_API_KEY": "sk-proj-abc123xyz789",  // Replace with your actual key
            "NIA_API_URL": "https://apigcp.trynia.ai/"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="&#x22;Command not found: pipx&#x22; error">
    **Problem:** Getting "command not found" when trying to use pipx.

    **Solution:** Install pipx first:

    ```bash theme={null}
    # On macOS with Homebrew
    brew install pipx
    pipx ensurepath

    # On Windows
    pip install pipx
    pipx ensurepath

    # On Linux
    pip install pipx
    pipx ensurepath
    ```

    After installation, you may need to:

    1. Restart your terminal
    2. Add pipx to your PATH if not done automatically
    3. Verify installation with `pipx --version`
  </Accordion>

  <Accordion title="Rate limit exceeded">
    **Problem:** Getting rate limit errors when using Nia tools.

    **Solution:**

    * You've used your allocated requests for the current period
    * Check your usage at [app.trynia.ai](http://app.trynia.ai/)
    * Consider upgrading your plan for more requests
    * Free tier includes 3 indexing jobs and limited searches
  </Accordion>

  <Accordion title="Vault: iMessage / Apple Notes / Contacts indexing fails">
    **Problem:** The sync daemon can't read iMessage, Apple Notes, Contacts, or other personal data sources. You may see "permission denied" or "database locked" errors.

    **Solution:** Personal data sources require **Full Disk Access** on macOS:

    1. Open **System Settings** → **Privacy & Security** → **Full Disk Access**
    2. Click the `+` button and add your **terminal app** (Terminal, iTerm2, Warp, etc.)
    3. If running via an IDE terminal (VS Code, Cursor), add that IDE too
    4. Restart the sync daemon: `nia` (it auto-restarts the watcher)

    **Still failing?** Some sources need to be closed first:

    * **Notes**: Close the Apple Notes app before the first sync — the SQLite database can be locked by the app
    * **iMessage**: The `chat.db` can be locked if Messages.app is actively writing. Try quitting Messages briefly during the initial index
    * **Contacts**: If using iCloud sync, contacts may take a moment to appear in the local database

    <Note>
      The sync daemon reads these databases in read-only mode. It never modifies your messages, notes, or contacts.
    </Note>
  </Accordion>

  <Accordion title="Vault: workflow stuck in 'running' state">
    **Problem:** A vault workflow (ingest, sync, dream) appears stuck and won't complete.

    **Solution:**

    1. Check if the Hatchet worker is running: the workflow needs an active backend worker
    2. Cancel the stuck run: `nia vault cancel <vault-id>` or use the vault UI
    3. If the workflow lock is stuck, the cancel endpoint will release it
    4. Re-trigger: `nia vault refresh <vault-id>`

    Workflows have a 2-hour timeout. If a run exceeds this, it's automatically marked as failed and the lock is released.
  </Accordion>

  <Accordion title="GitHub app stuck during onboarding">
    **Problem:** The GitHub app installation doesn't complete or gets stuck during onboarding.

    **Solution:**

    1. Go to GitHub → Settings → Applications → Installed GitHub Apps
    2. Find and remove the **Nia** app
    3. Return to [app.trynia.ai](https://app.trynia.ai) and restart the onboarding process

    <Note>
      You don't have to give Nia access to your own repositories. The GitHub app connection is only used to avoid GitHub's API rate limits when indexing public repositories. You can skip granting access to personal repos entirely.
    </Note>
  </Accordion>
</AccordionGroup>

## Getting Help

If you're still experiencing issues:

1. **Check the main documentation**: Review the [installation guide](/integrations/installation/mcp) for detailed setup instructions
2. **Community support**: Join our Discord community for help from other users
3. **Direct support**: Contact us through [app.trynia.ai](http://app.trynia.ai/)
4. **Email support**: The most effective way to get help is to email [arlan@nozomio.com](mailto:arlan@nozomio.com)

<Note>
  **Pro tip:** When seeking help, include:

  * Your MCP client (Cursor, Claude Desktop, etc.) and version
  * Your operating system
  * The exact error message you're seeing
  * Your configuration (with API key redacted)
</Note>