Skip to main content
This guide helps you resolve common issues when using the Adist CLI tool.

​
Common Issues

Problem: You see the error message:
✘ No project is currently selected.
Run "adist init" or "adist switch" first.
Solution: Initialize a new project or switch to an existing one:
# Initialize a new project in the current directory
adist init my-project

# Or switch to an existing project
adist switch
Why this happens: Adist needs an active project context to perform searches and other operations.
Problem: Commands like query, chat, or reindex --summarize fail with API key errors.Solution: Configure your LLM provider and set the appropriate API key:For Anthropic Claude:
export ANTHROPIC_API_KEY='your-api-key-here'
adist llm-config
For OpenAI:
export OPENAI_API_KEY='your-api-key-here'
adist llm-config
For Ollama (local, no API key needed):
# Install Ollama from https://ollama.com/download
ollama pull llama3
adist llm-config
Add the export command to your ~/.bashrc, ~/.zshrc, or equivalent to persist the API key across sessions.
Problem: Search returns no results even though you know the content exists.Solution: Try these steps:
  1. Check if project is indexed: 
    adist list
    Look for your project and verify it’s been indexed.
  2. Reindex the project: 
    adist reindex
  3. Verify file types are supported: Adist indexes common file types (.md, .txt, .js, .ts, .py, .go, etc.). If your files use uncommon extensions, they may not be indexed.
  4. Try different search terms:
    • Use specific keywords from your files
    • Try file path searches: adist get "filename.js"
    • Use broader terms if specific ones don’t work
Problem: ✘ Current project not found or ✘ Project not foundSolution: List all projects and verify the project exists:
# List all projects
adist list

# If your project is missing, initialize it again
cd /path/to/your/project
adist init project-name
Advanced troubleshooting:
# Show debug information
adist list --debug

# Remove corrupted project and re-initialize
adist remove-project project-name
adist init project-name
Problem: Errors about file permissions when indexing or reading files.Solution:
  1. Check directory permissions: 
    ls -la
    Ensure you have read access to the files you’re trying to index.
  2. Verify Adist config directory permissions: 
    # macOS
ls -la ~/Library/Application\ Support/adist

# Linux
ls -la ~/.config/adist

# Windows
dir %APPDATA%\adist
  3. Fix permissions if needed: 
    # macOS/Linux
chmod -R u+rw ~/Library/Application\ Support/adist  # macOS
chmod -R u+rw ~/.config/adist  # Linux
Problem: Cannot connect to Ollama for local LLM features.Solution:
  1. Check if Ollama is running: 
    # Ollama runs as a background service
# Try accessing the API
curl http://localhost:11434/api/tags
  2. Start Ollama if not running: 
    # macOS/Linux
ollama serve
  3. Verify model is installed: 
    ollama list
  4. Pull a model if needed: 
    ollama pull llama3
  5. Reconfigure Adist: 
    adist llm-config
Problem: Code highlighting broken or strange characters when using --stream flag.Solution: This is expected behavior. Streaming mode shows real-time responses but has limited code highlighting.Use default mode for better formatting:
# Default mode with full code highlighting
adist query "your question"
adist chat

# Only use --stream if you need real-time responses
adist query "your question" --stream
adist chat --stream
Problem: Adist behaves erratically or shows unexpected errors.Solution: View and verify your configuration:
# Show storage locations
adist paths
Reset configuration (WARNING: This removes all projects):
# macOS
rm -rf ~/Library/Application\ Support/adist

# Linux
rm -rf ~/.config/adist

# Windows
rd /s /q %APPDATA%\adist
After resetting, reinitialize your projects:
cd /path/to/project
adist init project-name

​
Installation Issues

Problem: Cannot install Adist globally.Solution:
  1. Check Node.js version: 
    node --version
    Ensure you have Node.js installed. Adist requires Node.js v14 or higher.
  2. Use correct npm permissions: 
    # Option 1: Use npx instead
npx adist init my-project

# Option 2: Fix npm global permissions
# See: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
  3. Clear npm cache: 
    npm cache clean --force
npm install -g adist
Problem: After installation, adist command is not recognized.Solution:
  1. Check if npm global bin is in PATH: 
    npm config get prefix
  2. Add npm global bin to PATH: 
    # Add to ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"
  3. Reload your shell: 
    source ~/.bashrc  # or ~/.zshrc
  4. Alternative: Use npx: 
    npx adist init my-project

​
Performance Issues

Problem: Initial indexing takes a long time.Why this happens: Large projects with thousands of files can take time to index, especially with --summarize enabled.Solutions:
  1. Index without summaries first: 
    adist init my-project
# Add summaries later if needed
adist reindex --summarize
  2. Use Ollama for faster local summarization: 
    adist llm-config  # Select Ollama
adist reindex --summarize
  3. Exclude large directories: Add a .gitignore file to your project. Adist respects .gitignore patterns and won’t index excluded files.
Problem: Searches take too long to return results.Solution:
  1. Reindex with block-based method: 
    adist reindex
    Block-based indexing provides faster, more precise searches.
  2. Use more specific queries: More specific search terms return faster results than broad terms.
  3. Check project size: 
    adist list --debug
    Very large projects may benefit from being split into multiple smaller projects.

​
Getting Help

If you encounter an issue not listed here, please:
  • Check the GitHub repository for known issues
  • Submit a new issue with details about your problem
  • Include your operating system, Node.js version, and Adist version (adist --version)

​
Useful Debug Commands

When reporting issues, include output from these commands: 
# Show version
adist --version

# Show all projects with debug info
adist list --debug

# Show storage locations
adist paths

# Check Node.js version
node --version

# Check npm version
npm --version

Build docs developers (and LLMs) love

Get started for freeTalk to us