Troubleshooting

Troubleshooting

This page covers common issues you might encounter while using LLMDog and provides solutions to resolve them.

Installation Issues

Go Build Errors

Problem: Errors when building from source with go build

Solution:

1. Ensure you have Go 1.16 or higher installed:

   go version

2. Check for missing dependencies:

   go mod tidy

3. Try a clean build:

   go clean
   go build -o llmdog ./cmd/llmdog

Homebrew Installation Fails

Problem: Error when installing via Homebrew

Solution:

1. Update Homebrew:

   brew update

2. Check for conflicts:

   brew doctor

3. Try with verbose output to see detailed errors:

   brew install -v doganarif/LLMDog/LLMDog

Runtime Issues

Terminal Rendering Problems

Problem: Garbled text, missing UI elements, or display issues

Solution:

1. Ensure your terminal supports TUI applications and has proper UTF-8 support

2. Check terminal color support:

   echo $TERM

   It should be something like xterm-256color

3. Resize your terminal window to be at least 80x24 characters

4. If using Windows, try Windows Terminal instead of the traditional Command Prompt

"Command not found" After Installation

Problem: llmdog command not found even after installation

Solution:

1. Verify the installation path is in your PATH environment variable:

   # For Homebrew installation
   echo $PATH | grep -q "$(brew --prefix)/bin" && echo "In PATH" || echo "Not in PATH"
   
   # For manual installation to ~/bin
   echo $PATH | grep -q "$HOME/bin" && echo "In PATH" || echo "Not in PATH"

2. If installing from source, make sure you moved the binary to a directory in your PATH or added its location to your PATH

Clipboard Not Working

Problem: Content not copied to clipboard after pressing Enter

Solution:

1. Verify clipboard dependencies are installed:

   • On Linux, ensure you have xclip or xsel installed:

     # Debian/Ubuntu
     sudo apt install xclip
     
     # Fedora
     sudo dnf install xclip

   • On macOS, no additional dependencies are needed

   • On Windows, no additional dependencies are needed

2. Run the application with verbose output to see clipboard errors:

   BUBBLES_DEBUG=1 llmdog

No Files Displayed

Problem: LLMDog launches but doesn't show any files

Solution:

1. Check if the current directory is empty
2. Verify file permissions:

   ls -la

3. If using a non-empty directory, check if all files are hidden (starting with .) and toggle hidden files with the configuration option:

   # Edit config file
   nano ~/.config/llmdog/config.json
   # Set "showHiddenFiles": true
   

Feature-Specific Issues

Git Integration Not Working

Problem: Gitignored files are not properly marked or Git information is missing

Solution:

1. Verify you're in a valid Git repository:

   git status

2. Check if .gitignore file exists and is readable:

   cat .gitignore

3. Try running git check-ignore to test specific paths:

   git check-ignore -v path/to/file

Bookmark Problems

Problem: Bookmarks not saving or loading correctly

Solution:

1. Check the bookmarks file for corruption:

   cat ~/.config/llmdog/bookmarks.json

2. If the file is corrupted, try backing it up and creating a new one:

   mv ~/.config/llmdog/bookmarks.json ~/.config/llmdog/bookmarks.json.bak

3. Verify permissions on the config directory:

   ls -la ~/.config/llmdog

Content Search Not Finding Results

Problem: Content search doesn't find text that you know exists in files

Solution:

1. Verify content search mode is enabled (check status bar or toggle with Ctrl+S)
2. Remember that content search has a file size limit (1MB by default) to maintain performance
3. For binary files, content search may not work properly
4. Try searching for a smaller, unique substring of the text you're looking for

Performance Issues

Slow Operation in Large Repositories

Problem: LLMDog becomes very slow in repositories with many files

Solution:

1. Navigate to a subdirectory with fewer files before launching LLMDog
2. Use search functionality to filter to relevant files quickly
3. Avoid expanding all directories at once
4. Keep content search mode disabled until needed

High Memory Usage

Problem: LLMDog uses excessive memory

Solution:

1. Avoid selecting too many large files at once
2. Keep directory expansion minimal
3. If you need to select many files, consider creating multiple smaller selections and processing them separately

Output Issues

Markdown Not Formatted Correctly

Problem: Generated Markdown doesn't render correctly in the LLM chat

Solution:

1. Verify the output with a Markdown previewer
2. Check if the LLM chat interface has any Markdown rendering limitations
3. For very large outputs, you might need to split them into multiple messages

Token Limit Exceeded

Problem: LLM responds with a message about token limits being exceeded

Solution:

1. Check the estimated token count in the status bar before confirming selection
2. Select fewer files or smaller files
3. Focus on only the most relevant code sections
4. Consider using search to find and select only files containing specific keywords

Special Cases

WSL (Windows Subsystem for Linux) Issues

Problem: Terminal rendering or clipboard issues in WSL

Solution:

1. Ensure you're using Windows Terminal for better TUI support
2. Install clipboard utilities in WSL:

   sudo apt install xclip

3. Use WSL2 instead of WSL1 for better performance and compatibility

Remote SSH Sessions

Problem: Issues when running LLMDog over SSH

Solution:

1. Ensure your terminal supports 256 colors:

   export TERM=xterm-256color

2. For clipboard support, consider using X11 forwarding with your SSH connection:

   ssh -X user@remote

Reporting Issues

If you encounter an issue not covered in this guide:

1. Check the [GitHub Issues](https://github.com/doganarif/LLMDog/issues) to see if it's a known problem
2. If not, create a new issue with:
   • Detailed description of the problem
   • Steps to reproduce
   • Expected behavior
   • Actual behavior
   • System information (OS, terminal, Go version if applicable)
   • Any error messages