57 lines
3.2 KiB
Markdown
57 lines
3.2 KiB
Markdown
# 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.
|