Troubleshooting

Common Issues

Build and Installation

Build fails on installation

Symptoms: Error messages during plugin installation/build process.Solutions:

Ensure build tools are installed:

macOS
Linux
Windows

# Install Xcode Command Line Tools
xcode-select --install

# Install Rust (if building from source)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Ubuntu/Debian
sudo apt-get install build-essential curl

# Arch Linux
sudo pacman -S base-devel curl

# Install Rust (if building from source)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Ensure PowerShell execution policy allows scripts
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install Rust
# Download from https://rustup.rs/

Force rebuild:
```
:AvanteBuild
```
Try prebuilt binaries (don’t build from source):
```
build = "make BUILD_FROM_SOURCE=false"
```
Check Neovim version:
```
:version
```
Avante requires Neovim 0.10.1+.

Cargo/Rust errors

Symptoms: Errors mentioning cargo, rustc, or Rust compilation.Solutions:

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Update Rust:
```
rustup update
```

Use prebuilt binaries instead:

build = vim.fn.has("win32") ~= 0
    and "powershell -ExecutionPolicy Bypass -File Build.ps1 -BuildFromSource false"
    or "make",

Permission denied errors

Symptoms: Build fails with permission errors.Solutions:

Check file permissions:

ls -la ~/.local/share/nvim/lazy/avante.nvim/

Fix permissions:

chmod -R u+w ~/.local/share/nvim/lazy/avante.nvim/

Clean and reinstall:
```
:Lazy clean
:Lazy sync
```

API Keys and Authentication

API key not recognized

Symptoms: Avante prompts for API key every time, or shows “API key not set” errors.Solutions:

Set environment variables in shell profile:

# Add to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish

# For Claude
export ANTHROPIC_API_KEY=your-api-key
# OR use scoped key (recommended)
export AVANTE_ANTHROPIC_API_KEY=your-api-key

# For OpenAI
export OPENAI_API_KEY=your-api-key
# OR
export AVANTE_OPENAI_API_KEY=your-api-key

Reload shell configuration:
```
source ~/.bashrc  # or ~/.zshrc
```
Verify environment variable is set:
```
echo $ANTHROPIC_API_KEY
```
Restart Neovim after setting environment variables.

Claude Max/Pro authentication fails

Symptoms: Browser authentication for Claude Max doesn’t work.Solutions:

Ensure correct auth type:

providers = {
  claude = {
    auth_type = "max", -- or "pro"
  },
}

Switch provider to trigger auth:
```
:AvanteSwitchProvider claude
```
Follow browser prompts:
- A browser window should open
- Log in to Claude
- Authorize the application
- Copy the code shown
- Paste into Neovim prompt
Check for browser issues:
- Ensure default browser is set
- Try manually opening the URL shown in Neovim

Multiple API providers confusion

Symptoms: Wrong API key being used.Solution: Use scoped API keys to isolate Avante:

# Scoped keys (Avante only)
export AVANTE_ANTHROPIC_API_KEY=sk-ant-avante-key
export AVANTE_OPENAI_API_KEY=sk-avante-openai-key

# Global keys (other apps can use these)
export ANTHROPIC_API_KEY=sk-ant-global-key
export OPENAI_API_KEY=sk-global-key

Avante will prefer AVANTE_* keys if set.

UI and Display Issues

Sidebar not showing or flickering

Symptoms: Avante sidebar doesn’t appear, or flickers/disappears.Solutions:

Set global statusline:
```
vim.opt.laststatus = 3
```
Refresh Avante:
```
:AvanteRefresh
```
Check for plugin conflicts (especially with other UI plugins).
Try toggling sidebar:
```
:AvanteToggle
```

Markdown rendering issues

Symptoms: Code blocks or markdown not rendering correctly.Solutions:

Ensure render-markdown.nvim is installed:

{
  'MeanderingProgrammer/render-markdown.nvim',
  opts = {
    file_types = { "markdown", "Avante" },
  },
  ft = { "markdown", "Avante" },
}

Add Avante to file types:
```
file_types = { "markdown", "Avante" },
```
Check treesitter parsers:
```
:TSInstall markdown markdown_inline
```

Diff highlights not showing

Symptoms: Can’t see conflict highlights when AI suggests changes.Solutions:

Enable auto highlight groups:

behaviour = {
  auto_set_highlight_group = true,
}

Check colorscheme compatibility: Some colorschemes don’t define DiffText/DiffAdd. Set manually:

highlights = {
  diff = {
    current = "DiffText",
    incoming = "DiffAdd",
  },
}

Try different highlights:

highlights = {
  diff = {
    current = "Visual",
    incoming = "Search",
  },
}

Icons not displaying

Symptoms: Missing or broken icons in UI.Solutions:

Install a Nerd Font:
- Download from nerdfonts.com
- Install and set as terminal font

Install icon plugin:

dependencies = {
  "nvim-tree/nvim-web-devicons",
  -- OR
  "echasnovski/mini.icons",
}

Performance Issues

Slow responses from AI

Symptoms: Long wait times for AI responses.Solutions:

Increase timeout:

providers = {
  claude = {
    timeout = 60000, -- 60 seconds
  },
}

Use faster models:

model = "claude-3-haiku-20240307", -- Faster than Sonnet

Reduce context size:
- Use /compact to compress history
- Avoid adding too many files with @file
- Clear history with /clear
Check internet connection.

High API costs

Symptoms: Unexpected API bills.Solutions:

Disable auto-suggestions:

behaviour = {
  auto_suggestions = false,
}

Increase debounce/throttle:

suggestion = {
  debounce = 1000,
  throttle = 1000,
}

Use cheaper models:

provider = "claude",
auto_suggestions_provider = "claude", -- Not copilot
providers = {
  claude = {
    model = "claude-3-haiku-20240307",
  },
}

Disable token counting:

behaviour = {
  enable_token_counting = false,
}

Neovim freezing or lagging

Symptoms: Neovim becomes unresponsive.Solutions:

Update Neovim to latest version (0.10.1+).

Disable expensive features:

behaviour = {
  auto_suggestions = false,
  enable_token_counting = false,
}

Check for plugin conflicts:
```
:Lazy profile
```

Reduce spinner animation:

windows = {
  spinner = {
    editing = { "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" },
  },
}

Feature-Specific Issues

RAG service not working

Symptoms: @codebase doesn’t work, RAG errors.Solutions:

Ensure Docker is running:
```
docker ps
```

Check RAG configuration:

rag_service = {
  enabled = true,
  runner = "docker", -- or "nix"
}

Verify API keys:
```
echo $OPENAI_API_KEY
```
Remove and recreate container:
```
docker rm -fv avante-rag-service
```
Check container logs:
```
docker logs avante-rag-service
```

Web search not working

Symptoms: Web search tool fails or returns no results.Solutions:

Set API key:
```
export TAVILY_API_KEY=your-key
```

Check provider configuration:

web_search_engine = {
  provider = "tavily",
}

Verify internet connectivity.
Check API quota (may be exceeded).

Try different provider:

provider = "serpapi", -- Instead of tavily

Completions not showing (nvim-cmp/blink.cmp)

Symptoms: No slash commands, mentions, or shortcuts appear.Solutions:

Verify completion plugin is installed:

dependencies = {
  "hrsh7th/nvim-cmp",
  -- OR
  "saghen/blink.cmp",
}

For blink.cmp, configure sources:

sources = {
  compat = {
    "avante_commands",
    "avante_mentions",
    "avante_files",
  },
}

Ensure you’re in Avante chat input.
Check for source errors:
```
:messages
```

File selector (@file) not opening

Symptoms: Typing @file doesn’t open file picker.Solutions:

Configure selector provider:

selector = {
  provider = "telescope", -- or fzf_lua, mini_pick, snacks
}

Install required dependency:

dependencies = {
  "nvim-telescope/telescope.nvim",
}

Don’t use “native” with blink.cmp (known issue).

Compatibility Issues

Neovim version too old

Symptoms: Errors about missing functions or features.Solution: Upgrade to Neovim 0.10.1 or later:

macOS
Linux (AppImage)
Windows

brew update
brew upgrade neovim

curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim.appimage
chmod u+x nvim.appimage
./nvim.appimage --appimage-extract
sudo mv squashfs-root /usr/local/nvim
sudo ln -sf /usr/local/nvim/AppRun /usr/local/bin/nvim

Plugin conflicts

Common conflicts:

Other AI plugins: May conflict with keybindings or UI
Completion plugins: Ensure only nvim-cmp OR blink.cmp is active
UI plugins: May interfere with Avante’s sidebar

Solution: Use lazy.nvim’s enabled = false to disable conflicting plugins temporarily:

{
  "other-ai-plugin",
  enabled = false,
}

Known Issues

These are known issues with workarounds or pending fixes.

blink.cmp Native Selector

Issue: Using selector.provider = "native" with blink.cmp causes errors. Workaround: Use a different selector:

selector = {
  provider = "telescope", -- Not "native"
}

Copilot as Auto-Suggestions Provider

Issue: Using Copilot for auto_suggestions_provider can cause high API costs due to request frequency. Workaround: Use Claude or OpenAI instead:

auto_suggestions_provider = "claude", -- Not "copilot"

Or increase debounce/throttle if you must use Copilot:

suggestion = {
  debounce = 2000,
  throttle = 2000,
}

Fast Apply Token Limits

Issue: Fast Apply is limited to 16k tokens for input/output. Workaround: Break large files into smaller edits or use traditional mode.

Getting Help

GitHub Issues

Report bugs or request features

Discord Community

Get help from the community

Wiki

Community recipes and tricks

Discussions

Ask questions and share ideas

Debugging Tips

Check Messages

:messages

Look for error messages or warnings.

Enable Debug Mode

<Leader>ad

Or:

:AvanteToggleDebug

Check Logs

Look at Avante’s log files (location varies by OS):

:echo stdpath('cache') .. '/avante_prompts'

Minimal Config Test

Test with a minimal configuration to isolate the issue:

-- minimal.lua
vim.opt.runtimepath:append("~/.local/share/nvim/lazy/avante.nvim")
require('avante').setup({
  provider = "claude",
})

Run: nvim -u minimal.lua

Report Issue

If problem persists, report on GitHub with:

Neovim version (:version)
OS and architecture
Error messages
Minimal reproducible config

Installation

Installation guide

Configuration

Configuration reference

GitHub Issues

Report issues and get help

Get Started

Core Concepts

Configuration

Features

Providers

Advanced

Guides

Common Issues

Build and Installation

API Keys and Authentication

UI and Display Issues

Performance Issues

Feature-Specific Issues

Compatibility Issues

Known Issues

blink.cmp Native Selector

Copilot as Auto-Suggestions Provider

Fast Apply Token Limits

Getting Help

GitHub Issues

Discord Community

Wiki

Discussions

Debugging Tips

Installation

Configuration

GitHub Issues

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Features

Providers

Advanced

Guides

​Common Issues

​Build and Installation

​API Keys and Authentication

​UI and Display Issues

​Performance Issues

​Feature-Specific Issues

​Compatibility Issues

​Known Issues

​blink.cmp Native Selector

​Copilot as Auto-Suggestions Provider

​Fast Apply Token Limits

​Getting Help

GitHub Issues

Discord Community

Wiki

Discussions

​Debugging Tips

​Related Documentation

Installation

Configuration

GitHub Issues

Build docs developers (and LLMs) love

Common Issues

Build and Installation

API Keys and Authentication

UI and Display Issues

Performance Issues

Feature-Specific Issues

Compatibility Issues

Known Issues

blink.cmp Native Selector

Copilot as Auto-Suggestions Provider

Fast Apply Token Limits

Getting Help

Debugging Tips

Related Documentation