docs: add troubleshooting guide (fixes #263) #294
Conversation
WalkthroughAdds a new documentation file Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/TROUBLESHOOTING.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/TROUBLESHOOTING.md
23-23: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
73-73: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
113-113: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
128-128: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
135-135: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
166-166: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
184-184: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
191-191: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
210-210: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
224-224: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
231-231: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
241-241: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
258-258: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
| # Troubleshooting Guide | ||
|
|
||
| Common errors and solutions for Cortex Linux. | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| - [API Key Issues](#api-key-issues) | ||
| - [Installation Errors](#installation-errors) | ||
| - [Network & Connectivity](#network--connectivity) | ||
| - [Permission Problems](#permission-problems) | ||
| - [LLM Provider Issues](#llm-provider-issues) | ||
| - [Package Manager Conflicts](#package-manager-conflicts) | ||
| - [Performance Issues](#performance-issues) | ||
| - [Rollback & Recovery](#rollback--recovery) | ||
|
|
||
| --- | ||
|
|
||
| ## API Key Issues | ||
|
|
||
| ### Error: "No API key found" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| Error: No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable. | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Set the environment variable:** | ||
| ```bash | ||
| # For Claude (recommended) | ||
| export ANTHROPIC_API_KEY='sk-ant-api03-your-key-here' | ||
|
|
||
| # For OpenAI | ||
| export OPENAI_API_KEY='sk-your-key-here' | ||
| ``` | ||
|
|
||
| 2. **Add to shell config for persistence:** | ||
| ```bash | ||
| echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key"' >> ~/.bashrc | ||
| source ~/.bashrc | ||
| ``` | ||
|
|
||
| 3. **Use the setup wizard:** | ||
| ```bash | ||
| cortex wizard | ||
| ``` | ||
|
|
||
| 4. **For offline mode (no API key needed):** | ||
| ```bash | ||
| export CORTEX_PROVIDER=ollama | ||
| cortex install docker | ||
| ``` | ||
|
|
||
| ### Error: "API rate limit exceeded" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| Error: Rate limit exceeded. Please wait before trying again. | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
| 1. **Wait and retry:** | ||
| ```bash | ||
| sleep 60 && cortex install docker | ||
| ``` | ||
|
|
||
| 2. **Use a different provider temporarily:** | ||
| ```bash | ||
| export CORTEX_PROVIDER=ollama | ||
| ``` | ||
|
|
||
| ----- | ||
|
|
||
| ## Installation Errors | ||
|
|
||
| ### Error: "Package not found" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| E: Unable to locate package xyz | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Update package lists:** | ||
| ```bash | ||
| sudo apt update | ||
| ``` | ||
|
|
||
| 2. **Use natural language for better matching:** | ||
| ```bash | ||
| cortex install "text editor like vim" # Instead of exact package name | ||
| ``` | ||
|
|
||
| ### Error: "Dependency problems" | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Fix broken packages:** | ||
| ```bash | ||
| sudo apt --fix-broken install | ||
| ``` | ||
|
|
||
| 2. **Update and upgrade:** | ||
| ```bash | ||
| sudo apt update && sudo apt upgrade | ||
| ``` | ||
|
|
||
| ### Error: "dpkg lock" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| E: Could not get lock /var/lib/dpkg/lock-frontend | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Check what's using it:** | ||
| ```bash | ||
| sudo lsof /var/lib/dpkg/lock-frontend | ||
| ``` | ||
|
|
||
| 2. **Kill stuck apt process (use with caution):** | ||
| ```bash | ||
| sudo killall apt apt-get | ||
| ``` | ||
| ----- | ||
|
|
||
| ## Network & Connectivity | ||
|
|
||
| ### Error: "Could not resolve host" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| Could not resolve 'archive.ubuntu.com' | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Check internet connection:** | ||
| ```bash | ||
| ping -c 3 8.8.8.8 | ||
| ``` | ||
|
|
||
| 2. **Try different DNS (Safe Method):** | ||
| ```bash | ||
| echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf | ||
| ``` | ||
|
|
||
| ### Error: "SSL certificate problem" | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Update CA certificates:** | ||
| ```bash | ||
| sudo apt install ca-certificates | ||
| sudo update-ca-certificates | ||
| ``` | ||
|
|
||
| 2. **Check system time (SSL requires correct time):** | ||
| ```bash | ||
| timedatectl status | ||
| sudo timedatectl set-ntp true | ||
| ``` | ||
| ----- | ||
|
|
||
| ## Permission Problems | ||
|
|
||
| ### Error: "Permission denied" | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Run with sudo for system packages:** | ||
| ```bash | ||
| sudo cortex install docker --execute | ||
| ``` | ||
|
|
||
| 2. **Check file ownership:** | ||
| ```bash | ||
| ls -la ~/.cortex/ | ||
| ``` | ||
|
|
||
| ----- | ||
|
|
||
| ## LLM Provider Issues | ||
|
|
||
| ### Error: "Ollama not running" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| Error: Could not connect to Ollama at localhost:11434 | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Start Ollama:** | ||
| ```bash | ||
| ollama serve & | ||
| ``` | ||
|
|
||
| 2. **Install Ollama if missing:** | ||
| ```bash | ||
| curl -fsSL https://ollama.com/install.sh | sh | ||
| ``` | ||
|
|
||
| ### Error: "Context length exceeded" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| Error: This model's maximum context length is 4096 tokens | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Simplify your request:** | ||
| Instead of asking for a "complete development environment," try installing tools individually (e.g., "python development tools"). | ||
|
|
||
| 2. **Change Provider:** | ||
| Switch to a provider that supports larger context windows (e.g., Anthropic) using the wizard: | ||
| ```bash | ||
| cortex wizard | ||
| ``` | ||
| ----- | ||
|
|
||
| ## Package Manager Conflicts | ||
|
|
||
| ### Error: "Snap vs apt conflict" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| error: cannot install "firefox": classic confinement requires snaps | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Use snap with classic:** | ||
| ```bash | ||
| sudo snap install firefox --classic | ||
| ``` | ||
| ----- | ||
|
|
||
| ## Performance Issues | ||
|
|
||
| ### Slow AI responses | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Use local LLM:** | ||
| ```bash | ||
| export CORTEX_PROVIDER=ollama | ||
| ``` | ||
|
|
||
| 2. **Check network latency:** | ||
| ```bash | ||
| ping api.anthropic.com | ||
| ``` | ||
| ----- | ||
|
|
||
| ## Rollback & Recovery | ||
|
|
||
| ### How to undo an installation | ||
| ```bash | ||
| # View installation history | ||
| cortex history | ||
|
|
||
| # Rollback last installation | ||
| cortex rollback | ||
|
|
||
| # Rollback specific installation | ||
| cortex rollback <installation-id> | ||
| ``` | ||
|
|
||
| ### System recovery | ||
|
|
||
| If Cortex causes system issues: | ||
|
|
||
| 1. **Boot into recovery mode** | ||
| 2. **Use dpkg to fix:** | ||
| ```bash | ||
| sudo dpkg --configure -a | ||
| sudo apt --fix-broken install | ||
| ``` No newline at end of file |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify whether any README already links to the troubleshooting guide
rg -n --hidden -S "TROUBLESHOOTING\.md|Troubleshooting Guide|Troubleshooting" -g'README*' -g'!.git/**'Repository: cortexlinux/cortex
Length of output: 323
🏁 Script executed:
# Check the actual content around line 103 in README.md to see if it links to the troubleshooting guide
head -n 110 README.md | tail -n 20Repository: cortexlinux/cortex
Length of output: 361
🏁 Script executed:
# Check if there's a more comprehensive link further down in README.md that points to the troubleshooting guide
rg -n "docs/TROUBLESHOOTING" README.mdRepository: cortexlinux/cortex
Length of output: 44
Link the new troubleshooting guide from README.md. The comprehensive docs/TROUBLESHOOTING.md is not referenced in the main README, making it undiscoverable. README.md has a brief "Troubleshooting" section but does not link to the full guide. Either add a link in this PR or explicitly document that a follow-up PR will handle it.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
23-23: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
73-73: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
113-113: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
128-128: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
135-135: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
166-166: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
184-184: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
191-191: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
210-210: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
224-224: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
231-231: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
241-241: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
258-258: Horizontal rule style
Expected: ---; Actual: -----
(MD035, hr-style)
|
|
@mikejmorgan-ai Once you review and approve the new commit, we can link the new troubleshooting guide from README.md as suggested by the coderabbitai bot. Thanks. |
1 participant
Related Issue
Closes #263
Summary
This PR adds a comprehensive troubleshooting guide (
docs/TROUBLESHOOTING.md).It supersedes PR #280 by addressing the following review feedback:
sudo echo >>redirection withsudo tee.ntpdatewithtimedatectl.CORTEX_MODELenvironment variables.Checklist
[#263] docs: Add Comprehensive Troubleshooting GuideSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.