# Troubleshooting Guide

This guide is intended to help you with common issues you might encounter while using Owlen.

## Connection Failures to Ollama

If you are unable to connect to a local Ollama instance, here are a few things to check:

1.  **Is Ollama running?** Make sure the Ollama service is active. You can usually check this with `ollama list`.
2.  **Is the address correct?** By default, Owlen tries to connect to `http://localhost:11434`. If your Ollama instance is running on a different address or port, you will need to configure it in your `config.toml` file.
3.  **Firewall issues:** Ensure that your firewall is not blocking the connection.
4.  **Health check warnings:** Owlen now performs a provider health check on startup. If it fails, the error message will include a hint (either "start owlen-mcp-llm-server" or "ensure Ollama is running"). Resolve the hint and restart.

## Model Not Found Errors

Owlen surfaces this as `InvalidInput: Model '<name>' was not found`.

1. **Local models:** Run `ollama list` to confirm the model name (e.g., `llama3:8b`). Use `ollama pull <model>` if it is missing.
2. **Ollama Cloud:** Names may differ from local installs. Double-check https://ollama.com/models and remove `-cloud` suffixes.
3. **Fallback:** Switch to `mode = "local_only"` temporarily in `[mcp]` if the remote server is slow to update.

Fix the name in your configuration file or choose a model from the UI (`:model`).

## Terminal Compatibility Issues

Owlen is built with `ratatui`, which supports most modern terminals. However, if you are experiencing rendering issues, please check the following:

-   Your terminal supports Unicode.
-   You are using a font that includes the characters being displayed.
-   Try a different terminal emulator to see if the issue persists.

## Configuration File Problems

If Owlen is not behaving as you expect, there might be an issue with your configuration file.

-   **Location:** Run `owlen config path` to print the exact location (Linux, macOS, or Windows). Owlen now follows platform defaults instead of hard-coding `~/.config`.
-   **Syntax:** The configuration file is in TOML format. Make sure the syntax is correct.
-   **Values:** Check that the values for your models, providers, and other settings are correct.
-   **Automation:** Run `owlen config doctor` to migrate legacy settings (`mode = "legacy"`, missing providers) and validate the file before launching the TUI.

## Ollama Cloud Authentication Errors

If you see `Auth` errors when using the `ollama-cloud` provider:

1. Ensure `providers.ollama-cloud.api_key` is set **or** export `OLLAMA_API_KEY` / `OLLAMA_CLOUD_API_KEY` before launching Owlen.
2. Confirm the key has access to the requested models.
3. Avoid pasting extra quotes or whitespace into the config file—`owlen config doctor` will normalise the entry for you.

## Performance Tuning

If you are experiencing performance issues, you can try the following:

-   **Reduce context size:** A smaller context size will result in faster responses from the LLM.
-   **Use a less resource-intensive model:** Some models are faster but less capable than others.

If you are still having trouble, please [open an issue](https://github.com/Owlibou/owlen/issues) on our GitHub repository.