Troubleshooting

Common issues and solutions for Gentleman.Dots configuration

This guide covers common issues you might encounter when using Gentleman.Dots and their solutions.

Installation Issues

Homebrew Installation Fails

Error: Permission denied when installing Homebrew

Symptoms:

Permission denied @ dir_s_mkdir - /opt/homebrew

Solution:

1. Create Homebrew directory with correct permissions

   sudo mkdir -p /opt/homebrew
   sudo chown -R $(whoami) /opt/homebrew
   
2. Run Homebrew installation again

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
3. Add Homebrew to PATH

   For macOS:

   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
   eval "$(/opt/homebrew/bin/brew shellenv)"
   

   For Linux:

   echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.zshrc
   eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
   

Homebrew commands not found after installation

Symptoms:

brew: command not found

Solution:

The Homebrew path is not in your shell’s PATH. Add it manually:

Zsh

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Font Installation Issues

IosevkaTerm Nerd Font is required for proper icon rendering. Many visual glitches are caused by missing or incorrect fonts.

Icons not displaying correctly in terminal

Symptoms:

• Boxes or question marks instead of icons
• Misaligned prompt elements
• Strange characters in Neovim

Solution:

1. Verify font installation

   Check if IosevkaTerm Nerd Font is installed:

   macOS:

   fc-list | grep -i iosevka
   

   Linux:

   fc-list | grep -i iosevka
   
2. Install the font if missing

   macOS:

   brew tap homebrew/cask-fonts
   brew install --cask font-iosevka-term-nerd-font
   

   Linux:

   mkdir -p ~/.local/share/fonts
   wget -O ~/.local/share/fonts/Iosevka.zip https://github.com/ryanoasis/nerd-fonts/releases/download/v3.3.0/IosevkaTerm.zip
   unzip ~/.local/share/fonts/Iosevka.zip -d ~/.local/share/fonts/
   fc-cache -fv
   
3. Configure terminal to use the font

   Edit your terminal config:

   Alacritty (~/.config/alacritty/alacritty.toml):

   [font.normal]
   family = "IosevkaTerm NF"
   

   WezTerm (~/.config/wezterm/wezterm.lua):

   config.font = wezterm.font("IosevkaTerm NF")
   

   Kitty (~/.config/kitty/kitty.conf):

   font_family IosevkaTerm NF
   
4. Restart terminal

   Close and reopen your terminal for changes to take effect.

Shell Issues

Shell Not Changing After Installation

Default shell remains unchanged

Symptoms:

echo $SHELL
# Still shows /bin/bash instead of your chosen shell

Solution:

1. Find your shell path

   which nu   # for Nushell
   which fish # for Fish
   which zsh  # for Zsh
   
2. Add shell to /etc/shells

   sudo sh -c "echo $(which nu) >> /etc/shells"  # Replace 'nu' with your shell
   
3. Change default shell

   chsh -s $(which nu)  # Replace 'nu' with your shell
   
4. Logout and login again

   Changes take effect after a fresh login.

Nushell Configuration Issues

Nushell env.nu errors on macOS

Symptoms:

Error: Can't find /home/linuxbrew/.linuxbrew/bin

Solution:

The Linux Homebrew path is configured instead of macOS path. Update env.nu:

~/.config/nushell/env.nu

# Change from:
$env.PATH = ($env.PATH | prepend '/home/linuxbrew/.linuxbrew/bin')

# To:
$env.PATH = ($env.PATH | prepend '/opt/homebrew/bin')

Or run the automated fix from the install script:

awk -v search="/home/linuxbrew/.linuxbrew/bin" -v replace="/opt/homebrew/bin" '
  $0 ~ search {print replace; next}
  {print}
' ~/.config/nushell/env.nu > ~/.config/nushell/env.nu.tmp && mv ~/.config/nushell/env.nu.tmp ~/.config/nushell/env.nu

Starship prompt not showing in Nushell

Symptoms: Plain prompt without Starship styling

Solution:

Verify Starship is initialized in ~/.config/nushell/config.nu:

config.nu

# Should contain:
use ~/.cache/starship/init.nu

# Or for older Nushell versions:
mkdir ~/.cache/starship
starship init nu | save -f ~/.cache/starship/init.nu

Restart Nushell after adding.

Zsh Plugin Errors

Zsh plugins not loading

Symptoms:

command not found: carapace
-zsh: source: no such file or directory

Solution:

1. Install missing plugins

   brew install carapace zoxide atuin fzf
   brew install zsh-autosuggestions zsh-syntax-highlighting zsh-autocomplete
   
2. Verify plugin paths in .zshrc

   For macOS:

   BREW_BIN="/opt/homebrew/bin"
   source $(dirname $BREW_BIN)/share/zsh-autocomplete/zsh-autocomplete.plugin.zsh
   source $(dirname $BREW_BIN)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
   source $(dirname $BREW_BIN)/share/zsh-autosuggestions/zsh-autosuggestions.zsh
   

   For Linux:

   BREW_BIN="/home/linuxbrew/.linuxbrew/bin"
   source $(dirname $BREW_BIN)/share/zsh-autocomplete/zsh-autocomplete.plugin.zsh
   source $(dirname $BREW_BIN)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
   source $(dirname $BREW_BIN)/share/zsh-autosuggestions/zsh-autosuggestions.zsh
   
3. Reload configuration

   source ~/.zshrc
   

Neovim Issues

LazyVim Plugin Errors

Plugins not loading after installation

Symptoms:

Error detected while processing ...
Plugin not found: ...

Solution:

1. Sync plugins

   Open Neovim and run:

   :Lazy sync
   
2. Clear cache if issues persist

   rm -rf ~/.local/share/nvim
   rm -rf ~/.local/state/nvim
   rm -rf ~/.cache/nvim
   

   Then reopen Neovim and let LazyVim reinstall plugins.

3. Check for conflicting plugins

   Review ~/.config/nvim/lua/plugins/disabled.lua and ensure only one AI plugin is enabled.

LSP servers not working

Symptoms:

• No autocompletion
• No diagnostics
• “LSP client not attached” message

Solution:

1. Check LSP status

   In Neovim:

   :LspInfo
   

   This shows which LSP servers are attached.

2. Install language servers

   :Mason
   

   Then install required servers (e.g., typescript-language-server, lua-language-server).

3. Verify Node.js installation

   Many LSP servers require Node.js:

   node --version  # Should be 18+
   npm --version
   

   If not installed:

   brew install node
   
4. Restart Neovim

   Close and reopen Neovim to attach LSP servers.

AI Plugin Issues

OpenCode not working in Neovim

Symptoms:

• OpenCode commands not found
• OpenCode CLI not installed

Solution:

1. Install OpenCode CLI

   curl -fsSL https://opencode.ai/install | bash
   
2. Verify installation

   which opencode
   opencode --version
   
3. Check plugin is enabled

   In ~/.config/nvim/lua/plugins/disabled.lua:

   {
     "NickvanDyke/opencode.nvim",
     enabled = true,  -- Must be true
   }
   
4. Restart Neovim and sync

   :Lazy sync
   

Multiple AI plugins conflicting

Symptoms:

• Keybinding conflicts
• Multiple AI windows opening
• Unexpected behavior

Solution:

Only ONE AI plugin should be enabled at a time!

Edit ~/.config/nvim/lua/plugins/disabled.lua:

return {
  { "NickvanDyke/opencode.nvim", enabled = true },
  { "yetone/avante.nvim", enabled = false },
  { "CopilotC-Nvim/CopilotChat.nvim", enabled = false },
  { "olimorris/codecompanion.nvim", enabled = false },
  { "coder/claudecode.nvim", enabled = false },
}

Restart Neovim after changes.

Obsidian Integration Issues

Obsidian vault not found

Symptoms:

Error: workspace path does not exist: /your/notes/path

Solution:

1. Create vault directory

   mkdir -p /path/to/your/notes
   mkdir -p /path/to/your/notes/templates
   
2. Update obsidian.lua configuration

   Edit ~/.config/nvim/lua/plugins/obsidian.lua:

   opts = {
     workspaces = {
       {
         name = "personal",
         path = "/path/to/your/notes",  -- Update this path
       },
     },
   }
   
3. Restart Neovim

   Close and reopen Neovim.

Window Manager Issues

Tmux Not Auto-starting

Tmux doesn't start automatically

Symptoms: Shell opens without Tmux session

Solution:

Verify auto-start configuration in your shell config:

Zsh (.zshrc)

WM_VAR="/$TMUX"
WM_CMD="tmux"

function start_if_needed() {
    if [[ $- == *i* ]] && [[ -z "${WM_VAR#/}" ]] && [[ -t 1 ]]; then
        exec $WM_CMD
    fi
}

# At the end of .zshrc:
start_if_needed

Tmux plugins not installing

Symptoms:

• TPM (Tmux Plugin Manager) not found
• Plugins not loading

Solution:

1. Install TPM

   git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
   
2. Verify tmux.conf configuration

   ~/.tmux/tmux.conf should contain:

   set -g @plugin 'tmux-plugins/tpm'
   set -g @plugin 'tmux-plugins/tmux-sensible'
   # ... other plugins ...
   
   # Initialize TPM (keep this at the very bottom)
   run '~/.tmux/plugins/tpm/tpm'
   
3. Install plugins

   Inside Tmux, press: Ctrl+a then I (capital i)

   Or from command line:

   ~/.tmux/plugins/tpm/bin/install_plugins
   
4. Reload Tmux

   tmux source-file ~/.tmux.conf
   

Navigation Between Tmux and Neovim Not Working

Ctrl+hjkl navigation broken

Symptoms: Cannot navigate between Neovim and Tmux panes using Ctrl+h/j/k/l

Solution:

1. Verify Tmux plugin

   ~/.tmux/tmux.conf should have:

   set -g @plugin 'christoomey/vim-tmux-navigator'
   
2. Verify Neovim plugin

   ~/.config/nvim/lua/plugins/vim-tmux-navigation.lua should exist with:

   return {
     "alexghergh/nvim-tmux-navigation",
     config = function()
       require("nvim-tmux-navigation").setup({
         disable_when_zoomed = true,
       })
     end,
   }
   
3. Check keymaps

   ~/.config/nvim/lua/config/keymaps.lua should have:

   local nvim_tmux_nav = require("nvim-tmux-navigation")
   
   vim.keymap.set("n", "<C-h>", nvim_tmux_nav.NvimTmuxNavigateLeft)
   vim.keymap.set("n", "<C-j>", nvim_tmux_nav.NvimTmuxNavigateDown)
   vim.keymap.set("n", "<C-k>", nvim_tmux_nav.NvimTmuxNavigateUp)
   vim.keymap.set("n", "<C-l>", nvim_tmux_nav.NvimTmuxNavigateRight)
   
4. Reinstall plugins and reload

   # Tmux
   ~/.tmux/plugins/tpm/bin/install_plugins
   tmux source-file ~/.tmux.conf
   

   In Neovim:

   :Lazy sync
   

WSL-Specific Issues

Clipboard Not Working

Copy/paste between WSL and Windows broken

Symptoms: Cannot copy from Neovim to Windows clipboard or vice versa

Solution:

1. Install win32yank

   In Windows PowerShell (as Administrator):

   choco install win32yank
   
2. Verify win32yank is in PATH

   In WSL:

   which win32yank.exe
   

   If not found, add to PATH:

   export PATH="$PATH:/mnt/c/ProgramData/chocolatey/bin"
   
3. Configure Neovim clipboard

   Neovim should auto-detect win32yank.exe. Test with:

   :checkhealth
   

   Look for clipboard section.

Terminal Emulator Not Using WSL

Alacritty/WezTerm not launching into WSL

Solution for Alacritty:

Edit %APPDATA%\alacritty\alacritty.toml (Windows path):

[shell]
program = "wsl.exe"
args = ["--cd", "~"]

Solution for WezTerm:

Edit .wezterm.lua:

config.default_domain = 'WSL:Ubuntu'
config.front_end = "WebGpu"
config.max_fps = 120

Performance Issues

Slow shell startup time

Symptoms: Shell takes several seconds to become interactive

Diagnosis:

Zsh

# Add to .zshrc:
zmodload zsh/zprof
# ... your config ...
zprof  # Shows profiling info

Common Fixes:

1. Lazy-load plugins:

   # Instead of direct source, use autoload
   autoload -Uz compinit
   compinit -C  # Skip security check for faster load
   

2. Reduce completion cache:

   # In .zshrc:
   zstyle ':completion:*' cache-path ~/.zsh/cache
   

3. Disable unused plugins: Comment out plugins you don’t use in your shell config.

Neovim slow to open files

Diagnosis:

In Neovim:

:Lazy profile

Look for plugins with high load times.

Solution:

1. Lazy-load plugins:

   return {
     "plugin-name",
     lazy = true,  -- Don't load on startup
     cmd = "PluginCommand",  -- Load when command is used
     keys = { "<leader>key" },  -- Load when key is pressed
   }
   

2. Disable unused AI plugins: Ensure only one AI plugin is enabled in disabled.lua.

3. Clear old cache:

   rm -rf ~/.local/share/nvim/lazy
   

Getting Help

If you encounter an issue not covered here, please check the GitHub repository for similar issues or create a new one.

GitHub Issues

Report bugs or request features

Customization Guide

Learn how to customize your setup