Troubleshooting

# Install Node.js: https://nodejs.org (LTS recommended)
node --version # Should return v18+
npm --version # Should return 9+

# Configure npm for local installation
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Add the line above to your ~/.bashrc or ~/.zshrc
npm install -g @kaffyn/vectora

# Verify installation
npm list -g @kaffyn/vectora

# Reinstall
npm install -g @kaffyn/vectora

# Test
vectora --version

# Verify if keys are defined
echo $GEMINI_API_KEY
echo $VOYAGE_API_KEY

# If empty, configure
export GEMINI_API_KEY="your_key_here"
export VOYAGE_API_KEY="your_key_here"

# Or create a .env file
cat > .env << 'EOF'
GEMINI_API_KEY=sk-xxx
VOYAGE_API_KEY=pa-xxx
EOF

# Validate YAML
yamllint vectora.config.yaml

# Or use online: https://yamllint.com

# Common errors:
# - Inconsistent indentation (use 2 spaces)
# - Missing quotes around values
# - Unescaped special symbols

# Update vectora.config.yaml
namespace:
  trust_folder: "." # or a valid path

{
  "mcpServers": {
    "vectora": {
      "command": "vectora",
      "args": ["mcp-serve"]
    }
  }
}

# Verify API keys
echo $GEMINI_API_KEY
echo $VOYAGE_API_KEY

# Test connectivity
curl https://generativelanguage.googleapis.com/v1beta/models

# If it fails, your key might be invalid
# Generate a new key at https://aistudio.google.com/app/apikey

Use Vectora to search for context about authentication.
Search the codebase for JWT implementations.

# Wait for quota reset (next minute)
# Or upgrade to Plus plan at https://vectora.dev/plans

# For debug: verify usage
vectora stats --provider gemini

# Generate new key at https://dash.voyageai.com/api-keys
vectora config set --key VOYAGE_API_KEY --value "new_key"

# Test
vectora test --provider voyage

# Increase timeout (default: 30s)
export VECTORA_TIMEOUT_MS=60000

# Test connectivity
ping generativelanguage.googleapis.com

# If using VPN/proxy:
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=https://proxy:port

# Initialize project
vectora init --name "My Project"

# Or specify in claude_desktop_config.json
"VECTORA_NAMESPACE": "my-project"

# Force reindexing
vectora ingest --project . --force

# Verify status
vectora status --project .

# Try a different or more specific query
# Example: instead of "auth", try "JWT validation in middleware"

# Use batch processing
vectora ingest --batch-size 16 # default: 32

# Or configure in vectora.config.yaml
indexing:
  batch_size: 16

# For local development, use fallback
providers:
  embedding:
    fallback: "local" # local embedding via ollama

# Limit automatic indexing
vectora config set VECTORA_AUTO_INGEST=false

# Or schedule indexing for off-peak times
vectora schedule ingest --time 02:00 --recurring daily

# Clear cache
vectora cache clear

# Reduce cache size
vectora config set VECTORA_CACHE_SIZE=100MB

# Verify consumption
vectora stats --memory

# Via CLI
vectora --log-level debug

# Via variable
export VECTORA_LOG_LEVEL=debug

# Save logs to file
vectora mcp-serve --log-file debug.log

# General status
vectora status

# Configuration details
vectora config list

# Usage statistics
vectora stats

# Verify indexing
vectora index --list --verbose