Troubleshooting

`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:

Uninstall the old package:

pip uninstall nia-sync   # or: uv pip uninstall nia-sync

Clear your shell’s command cache and verify:

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

On Windows (PowerShell):

Get-Command nia      # should point to the new CLI, not a pip path

Re-run the wizard:

npx nia-wizard@latest

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.Example:

# For Cursor on macOS
mkdir -p ~/.cursor
touch ~/.cursor/mcp.json

Then add the configuration:

{
  "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/"
      }
    }
  }
}

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:

# 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:

Update your MCP configuration to use pipx run
Restart your MCP client completely
Check if tools appear in the MCP tools section

If you previously installed with pip, uninstall first:

pip uninstall nia-mcp-server
pipx install nia-mcp-server

"No API key provided" error

Problem: Getting an error that no API key was provided.Solution:

Ensure you’ve replaced YOUR_API_KEY with your actual API key from app.trynia.ai
Check that the environment variable is correctly set in your MCP configuration
Verify there are no typos in the environment variable name NIA_API_KEY
Make sure there are no extra spaces or hidden characters in your API key

Example of correct configuration:

{
  "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/"
      }
    }
  }
}

"Command not found: pipx" error

Problem: Getting “command not found” when trying to use pipx.Solution: Install pipx first:

# 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:

Restart your terminal
Add pipx to your PATH if not done automatically
Verify installation with pipx --version

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
Consider upgrading your plan for more requests
Free tier includes 3 indexing jobs and limited searches

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:

Open System Settings → Privacy & Security → Full Disk Access
Click the + button and add your terminal app (Terminal, iTerm2, Warp, etc.)
If running via an IDE terminal (VS Code, Cursor), add that IDE too
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

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

Vault: workflow stuck in 'running' state

Problem: A vault workflow (ingest, sync, dream) appears stuck and won’t complete.Solution:

Check if the Hatchet worker is running: the workflow needs an active backend worker
Cancel the stuck run: nia vault cancel <vault-id> or use the vault UI
If the workflow lock is stuck, the cancel endpoint will release it
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.

GitHub app stuck during onboarding

Problem: The GitHub app installation doesn’t complete or gets stuck during onboarding.Solution:

Go to GitHub → Settings → Applications → Installed GitHub Apps
Find and remove the Nia app
Return to app.trynia.ai and restart the onboarding process

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.

Getting Started

Capabilities

Source Types

Explore

Examples & Guides

Enterprise

Privacy

Common Issues

Getting Help

​Common Issues

​Getting Help

Common Issues

Getting Help