Skip to content
hordecode
app.header.homeapp.header.docs

Troubleshooting

Common issues and how to resolve them.

To debug issues with hordecode, start by checking the logs and local data it stores on disk.

Logs

Log files are written to:

  • macOS/Linux: ~/.local/share/hordecode/log/
  • Windows: Press WIN+R and paste %USERPROFILE%\.local\share\hordecode\log

Log files are named with timestamps (e.g., 2025-01-09T123456.log) and the most recent 10 log files are kept.

You can set the log level with the --log-level command-line option to get more detailed debug information. For example, horde --log-level DEBUG.

Storage

hordecode stores session data and other application data on disk at:

  • macOS/Linux: ~/.local/share/hordecode/
  • Windows: Press WIN+R and paste %USERPROFILE%\.local\share\hordecode

This directory contains:

  • auth.json - Authentication data like API keys, OAuth tokens
  • log/ - Application logs
  • project/ - Project-specific data like session and message data
    • If the project is within a Git repo, it is stored in ./<project-slug>/storage/
    • If it is not a Git repo, it is stored in ./global/storage/

Uninstall

To uninstall the hordecode CLI and remove its related files, run:

Terminal window
horde uninstall

The command shows what will be removed and asks for confirmation. See the CLI reference for options to keep your configuration or application data.

Windows: General performance issues

If you’re experiencing slow performance, file access issues, or terminal problems on Windows, try using WSL (Windows Subsystem for Linux). WSL provides a Linux environment that works more seamlessly with hordecode’s features.

Getting help

If you’re experiencing issues with hordecode:

  1. Report issues on GitHub

    The best way to report bugs or request features is through our GitHub repository:

    github.com/siliconstencil/hordecode/issues

    Before creating a new issue, search existing issues to see if your problem has already been reported.

Common issues

Here are some common issues and how to resolve them.

hordecode won’t start

  1. Check the logs for error messages
  2. Try running with --print-logs to see output in the terminal
  3. Ensure you have the latest version with horde upgrade

Authentication issues

  1. Try re-authenticating with the /connect command in the TUI
  2. Check that your API keys are valid
  3. Ensure your network allows connections to the provider’s API

Model not available

  1. Check that you’ve authenticated with the provider
  2. Verify the model name in your config is correct
  3. Some models may require specific access or subscriptions

If you encounter ProviderModelNotFoundError you are most likely incorrectly referencing a model somewhere. Models should be referenced like so: <providerId>/<modelId>

Examples:

  • openai/gpt-4.1
  • openrouter/google/gemini-2.5-flash
  • hordecode/kimi-k2

To figure out what models you have access to, run horde models

ProviderInitError

If you encounter a ProviderInitError, you likely have an invalid or corrupted configuration.

To resolve this:

  1. First, verify your provider is set up correctly by following the providers guide

  2. If the issue persists, try clearing your stored configuration:

    Terminal window
    rm -rf ~/.local/share/hordecode

    On Windows, press WIN+R and delete: %USERPROFILE%\.local\share\hordecode

  3. Re-authenticate with your provider using the /connect command in the TUI.

AI_APICallError and provider package issues

If you encounter API call errors, this may be due to outdated provider packages. hordecode dynamically installs provider packages (OpenAI, Anthropic, Google, etc.) as needed and caches them locally.

To resolve provider package issues:

  1. Clear the provider package cache:

    Terminal window
    rm -rf ~/.cache/hordecode

    On Windows, press WIN+R and delete: %USERPROFILE%\.cache\hordecode

  2. Restart hordecode to reinstall the latest provider packages

This will force hordecode to download the most recent versions of provider packages, which often resolves compatibility issues with model parameters and API changes.

Copy/paste not working on Linux

Linux users need to have one of the following clipboard utilities installed for copy/paste functionality to work:

For X11 systems:

Terminal window
apt install -y xclip
# or
apt install -y xsel

For Wayland systems:

Terminal window
apt install -y wl-clipboard

For headless environments:

Terminal window
apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

hordecode will detect if you’re using Wayland and prefer wl-clipboard, otherwise it will try to find clipboard tools in order of: xclip and xsel.