Troubleshooting

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:

Create Homebrew directory with correct permissions

sudo mkdir -p /opt/homebrew
sudo chown -R $(whoami) /opt/homebrew

Run Homebrew installation again

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

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:

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:

Verify font installation

Check if IosevkaTerm Nerd Font is installed:macOS:

fc-list | grep -i iosevka

Linux:

fc-list | grep -i iosevka

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

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

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:

Find your shell path

which nu   # for Nushell
which fish # for Fish
which zsh  # for Zsh

Add shell to /etc/shells

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

Change default shell

chsh -s $(which nu)  # Replace 'nu' with your shell

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 stylingSolution: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:

Install missing plugins

brew install carapace zoxide atuin fzf
brew install zsh-autosuggestions zsh-syntax-highlighting zsh-autocomplete

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

Reload configuration

source ~/.zshrc

Neovim Issues

LazyVim Plugin Errors

Plugins not loading after installation

Symptoms:

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

Solution:

Sync plugins

Open Neovim and run:

:Lazy sync

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.

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:

Check LSP status

In Neovim:

:LspInfo

This shows which LSP servers are attached.

Install language servers

:Mason

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

Verify Node.js installation

Many LSP servers require Node.js:

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

If not installed:

brew install node

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:

Install OpenCode CLI

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

Verify installation

which opencode
opencode --version

Check plugin is enabled

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

{
  "NickvanDyke/opencode.nvim",
  enabled = true,  -- Must be true
}

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:

Create vault directory

mkdir -p /path/to/your/notes
mkdir -p /path/to/your/notes/templates

Update obsidian.lua configuration

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

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

Restart Neovim

Close and reopen Neovim.

Window Manager Issues

Tmux Not Auto-starting

Tmux doesn't start automatically

Symptoms: Shell opens without Tmux sessionSolution:Verify auto-start configuration in your shell config:

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:

Install TPM

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

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'

Install plugins

Inside Tmux, press: Ctrl+a then I (capital i)Or from command line:

~/.tmux/plugins/tpm/bin/install_plugins

Reload Tmux

tmux source-file ~/.tmux.conf

Ctrl+hjkl navigation broken

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

Verify Tmux plugin

~/.tmux/tmux.conf should have:

set -g @plugin 'christoomey/vim-tmux-navigator'

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,
}

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)

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 versaSolution:

Install win32yank

In Windows PowerShell (as Administrator):

choco install win32yank

Verify win32yank is in PATH

In WSL:

which win32yank.exe

If not found, add to PATH:

export PATH="$PATH:/mnt/c/ProgramData/chocolatey/bin"

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 interactiveDiagnosis:

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

Common Fixes:

Lazy-load plugins:

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

Reduce completion cache:

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

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:

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
}

Disable unused AI plugins: Ensure only one AI plugin is enabled in disabled.lua.
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

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

Installation Issues

Homebrew Installation Fails

Font Installation Issues

Shell Issues

Shell Not Changing After Installation

Nushell Configuration Issues

Zsh Plugin Errors

Neovim Issues

LazyVim Plugin Errors

AI Plugin Issues

Obsidian Integration Issues

Window Manager Issues

Tmux Not Auto-starting

Navigation Between Tmux and Neovim Not Working

WSL-Specific Issues

Clipboard Not Working

Terminal Emulator Not Using WSL

Performance Issues

Getting Help

GitHub Issues

Customization Guide

Build docs developers (and LLMs) love

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Installation Issues

​Homebrew Installation Fails

​Font Installation Issues

​Shell Issues

​Shell Not Changing After Installation

​Nushell Configuration Issues

​Zsh Plugin Errors

​Neovim Issues

​LazyVim Plugin Errors

​AI Plugin Issues

​Obsidian Integration Issues

​Window Manager Issues

​Tmux Not Auto-starting

​Navigation Between Tmux and Neovim Not Working

​WSL-Specific Issues

​Clipboard Not Working

​Terminal Emulator Not Using WSL

​Performance Issues

​Getting Help

GitHub Issues

Customization Guide

Build docs developers (and LLMs) love

Installation Issues

Homebrew Installation Fails

Font Installation Issues

Shell Issues

Shell Not Changing After Installation

Nushell Configuration Issues

Zsh Plugin Errors

Neovim Issues

LazyVim Plugin Errors

AI Plugin Issues

Obsidian Integration Issues

Window Manager Issues

Tmux Not Auto-starting

Navigation Between Tmux and Neovim Not Working

WSL-Specific Issues

Clipboard Not Working

Terminal Emulator Not Using WSL

Performance Issues

Getting Help