Troubleshooting¶

Common issues and their solutions.

Installation Issues¶

Command Not Found: nexus-init¶

Symptom:

zsh: command not found: nexus-init

Solutions:

Check installation:
```
pip show nexus-dev
```

Reinstall with pipx:

pipx uninstall nexus-dev
pipx install nexus-dev
pipx ensurepath

Restart shell:
```
source ~/.zshrc  # or ~/.bashrc
```

Python Version Error¶

Symptom:

ERROR: Package requires Python >=3.13

Solution:

Install Python 3.13+:

# macOS with pyenv
pyenv install 3.13
pyenv global 3.13

# Then reinstall
pipx reinstall nexus-dev

Configuration Issues¶

"nexus_config.json not found"¶

Symptom:

❌ nexus_config.json not found. Run 'nexus-init' first.

Solutions:

Initialize the project:
```
nexus-init --project-name "My Project"
```

Check working directory:

pwd  # Should be project root
ls nexus_config.json

OpenAI API Key Error¶

Symptom:

Error: OPENAI_API_KEY not set

Solution:

export OPENAI_API_KEY="sk-..."

# Or add to shell profile
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc

Indexing Issues¶

No Files Indexed¶

Symptom:

No files to index.

Causes & Solutions:

Wrong patterns in config: Check nexus_config.json:

{
  "include_patterns": ["**/*.py", "**/*.js"],
  "exclude_patterns": ["**/node_modules/**"]
}

Missing -r flag:
```
nexus-index src/ -r  # Recursive
```
All files excluded: Check if files match exclude patterns.

Chunking Errors¶

Symptom:

❌ Failed to index file.py: syntax error

Cause: Invalid syntax in source file.

Solution: Fix syntax errors before indexing. The file is skipped, not fatal.

MCP Server Issues¶

Server Not Connecting¶

Symptom: AI agent doesn't see Nexus-Dev tools.

Solutions:

Restart IDE after configuration changes.

Check MCP config syntax:

{
  "mcpServers": {
    "nexus-dev": {
      "command": "nexus-dev",
      "args": []
    }
  }
}

Test server manually:

nexus-dev
# Should start without errors
# Ctrl+C to exit

"Empty" Server (No Project Context)¶

Symptom: Server connects but has no project data.

Solutions:

Set project root:

{
  "env": {
    "NEXUS_PROJECT_ROOT": "/path/to/project"
  }
}

Use refresh_agents:
```
Call the refresh_agents tool
```

Search Issues¶

No Results Found¶

Symptom:

No results found for query: 'function name'

Solutions:

Check if indexed:
```
nexus-status
```
Should show non-zero chunk counts.
Re-index:
```
nexus-reindex
```
Try broader query: Use natural language instead of exact names.

Wrong Results¶

Symptom: Results don't match what you're looking for.

Solutions:

Be more specific: "function that validates email addresses" > "validate"

Use type filters:

search_code("email validator")  # Code only
search_docs("how to validate")  # Docs only

Gateway Issues¶

"Server not found"¶

Symptom:

Server not found: github

Solutions:

Check config:
```
cat .nexus/mcp_config.json
```
Verify server name matches config key.
Initialize config:
```
nexus-mcp init --from-global
```

"Connection refused"¶

Symptom:

Error connecting to server: Connection refused

Solutions:

For SSE servers: Verify URL is accessible
```
curl http://server-url/mcp
```

For stdio servers: Check command works

npx -y @modelcontextprotocol/server-github

Check credentials in env configuration.

Agent Issues¶

Agent Not Appearing¶

Symptom: ask_* tool not available.

Solutions:

Refresh agents:
```
refresh_agents()
```

Check YAML syntax:

python -c "import yaml; yaml.safe_load(open('agents/agent.yaml'))"

Verify file location: Agents must be in agents/ directory at project root.

Agent Returns Generic Responses¶

Symptom: Agent doesn't use RAG context.

Solutions:

Check memory config:

memory:
  enabled: true
  rag_limit: 10

Ensure content is indexed:
```
nexus-status
```

Database Issues¶

"Table not found"¶

Symptom:

LanceDB error: Table 'documents' not found

Solution:

nexus-reindex  # Rebuilds database schema

Database Corruption¶

Symptom: Random errors accessing database.

Solution:

Backup lessons:

cp -r .nexus/lessons .nexus/lessons.bak

Delete database:

rm -rf ~/.local/share/nexus-dev/lancedb/*

Re-index:
```
nexus-reindex
```

Getting Help¶

Debug Output¶

Run with verbose logging:

LOGLEVEL=DEBUG nexus-dev

Report Issues¶

GitHub Issues

Include: - Nexus-Dev version (nexus-init --version) - Python version (python --version) - OS and version - Full error message - Steps to reproduce