docs: Comprehensive Troubleshooting Guide (Issue #263) #280
Conversation
Implements Issue #263 - Common errors and solutions guide This guide helps users diagnose and fix common issues they may encounter when using Cortex Linux. Sections covered: - API Key Issues: missing keys, invalid formats, rate limits - Installation Errors: package not found, dependencies, dpkg locks - Network & Connectivity: DNS, timeouts, SSL certificates - Permission Problems: sudo requirements, file ownership - LLM Provider Issues: Ollama setup, model selection - Package Manager Conflicts: apt/snap conflicts - Performance Issues: slow responses, memory usage - Rollback & Recovery: undo installations, system recovery Additional features: - Quick reference error code table - Step-by-step solutions for each error - Links to community support resources - Verbose mode and logging instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
WalkthroughA comprehensive troubleshooting guide is added to Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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: 4
🧹 Nitpick comments (5)
docs/TROUBLESHOOTING.md (5)
23-25: Add language specifiers to symptom code blocks.Fenced code blocks should specify a language for proper syntax highlighting. Symptom blocks showing error messages should use
textas the language identifier.Apply this diff pattern to all symptom blocks (lines 23, 58, 81 and others):
-**Symptom:** -``` -Error: No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable. -``` +**Symptom:** +```text +Error: No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable. +```Repeat for all other symptom sections throughout the document.
Also applies to: 58-60, 81-83
106-108: Symptom blocks need language specifier (recurring pattern).All error symptom blocks throughout the document should use
textlanguage specifier for consistency and proper rendering (see previous comment for pattern).Also applies to: 136-139, 167-169, 194-197
264-267: Note GUI tool limitation in headless environments.Line 266 references
software-properties-gtk, which is a GUI application unsuitable for headless servers, SSH sessions, or CI/CD automation. Clarify that this solution is for desktop environments only, or provide a CLI alternative.Add a note above the command or provide an alternative for headless systems:
-2. **Try different mirror:** +2. **Try different mirror (GUI on desktop systems):** ```bash sudo software-properties-gtk # Change download server ``` + + Or via command line: + ```bash + sudo sed -i 's/archive.ubuntu.com/mirror.example.com/g' /etc/apt/sources.list + sudo apt update + ```
470-505: Restructure Performance Issues section for consistency.This section lacks the "Symptom:" headers present in all other error sections, making it structurally inconsistent. Additionally, "slow responses" and "high memory usage" are performance optimization tips rather than error troubleshooting (which is the document's primary purpose).
Consider either:
- Reframe these as symptoms with corresponding error messages (e.g., "Response takes > X seconds")
- Move this section to a separate "Performance Tuning" guide
- Keep it as-is but note this is an optimization guide, not error troubleshooting
553-567: Wrap bare URLs in markdown link format.Lines 561, 565, and 566 contain bare URLs that should be wrapped in angle brackets or converted to proper markdown links for better rendering and accessibility.
Replace bare URLs with markdown formatted links:
-2. Open an issue: https://github.com/cortexlinux/cortex/issues +2. Open an issue: <https://github.com/cortexlinux/cortex/issues> ### Community support -- Discord: https://discord.gg/uCqHvxjU83 -- GitHub Discussions: https://github.com/cortexlinux/cortex/discussions +- Discord: <https://discord.gg/uCqHvxjU83> +- GitHub Discussions: <https://github.com/cortexlinux/cortex/discussions>Alternatively, use markdown link syntax:
- [GitHub Issues](https://github.com/cortexlinux/cortex/issues) - [Discord Community](https://discord.gg/uCqHvxjU83)
📜 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)
81-81: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
136-136: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
167-167: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
194-194: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
223-223: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
253-253: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
278-278: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
303-303: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
327-327: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
351-351: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
380-380: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
404-404: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
431-431: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
451-451: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
561-561: Bare URL used
(MD034, no-bare-urls)
565-565: Bare URL used
(MD034, no-bare-urls)
566-566: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (4)
docs/TROUBLESHOOTING.md (4)
1-16: Clean structure and comprehensive table of contents.The document organization is well-structured with a complete TOC and clear section headings. The metadata is minimal but appropriate.
Also applies to: 585-588
298-344: Verify Cortex CLI command flags and syntax.Line 311 references
cortex install docker --executeflag. Confirm this flag exists and has the correct syntax.
570-584: Error Code Reference table is clear and helpful.The error code mapping provides a quick lookup for common issues. The table is well-organized and aligns with the troubleshooting sections above.
539-551: No action required—documentation is accurate.Both references are correct:
- The
-vverbose flag is properly implemented incortex/cli.py(line 817) as--verbosewith short form-v- The log path
~/.cortex/logs/cortex.logmatches the CortexLogger implementation incortex/logging_system.py(default log directory~/.cortex/logsand log filename{name}.logwhere name defaults tocortex)
| 3. **Try different DNS:** | ||
| ```bash | ||
| sudo echo "nameserver 8.8.8.8" >> /etc/resolv.conf | ||
| ``` |
There was a problem hiding this comment.
Fix unsafe DNS configuration command.
The shell redirection doesn't work with sudo in this form. The redirect operator (>>) is processed by the current shell before echo executes.
Replace with a command that properly escalates privileges:
- sudo echo "nameserver 8.8.8.8" >> /etc/resolv.conf
+ echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf🤖 Prompt for AI Agents
In docs/TROUBLESHOOTING.md around lines 240 to 243, the example using sudo with
shell redirection is unsafe/incorrect because the shell handles >> before sudo
runs; replace the snippet with a privileged-safe command such as using tee or
running the echo under a root shell (for example use sudo tee -a
/etc/resolv.conf or sudo sh -c 'echo "nameserver 8.8.8.8" >> /etc/resolv.conf'),
and mention that users may need appropriate privileges and to prefer editing
resolv.conf via their distro’s recommended method
(NetworkManager/systemd-resolved) where applicable.
| 2. **Check system time (SSL requires correct time):** | ||
| ```bash | ||
| date | ||
| sudo ntpdate pool.ntp.org | ||
| ``` |
There was a problem hiding this comment.
Replace deprecated ntpdate with modern time-sync utility.
The ntpdate utility is deprecated and removed from modern Linux distributions (Ubuntu 21.04+, Debian 11+). Use timedatectl instead, which is available on systemd-based systems.
Replace with:
- sudo ntpdate pool.ntp.org
+ timedatectl # Check current time and sync status
+ sudo timedatectl set-ntp true # Enable NTP sync🤖 Prompt for AI Agents
In docs/TROUBLESHOOTING.md around lines 290–294, replace the deprecated ntpdate
instructions with guidance to use systemd's timedatectl: instruct readers to
enable NTP synchronization via timedatectl, verify the system clock and NTP sync
status with timedatectl status/queries, and advise enabling or starting the
system time synchronization service if not active; update the wording to mention
that timedatectl is available on systemd-based distributions and remove the
ntpdate example.
| ## 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. **Check if running:** | ||
| ```bash | ||
| curl http://localhost:11434/api/tags | ||
| ``` | ||
|
|
||
| 3. **Install Ollama if missing:** | ||
| ```bash | ||
| curl -fsSL https://ollama.ai/install.sh | sh | ||
| ``` | ||
|
|
||
| 4. **Pull required model:** | ||
| ```bash | ||
| ollama pull llama2 | ||
| ``` | ||
|
|
||
| ### Error: "Model not found" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| Error: model 'xyz' not found | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **List available models:** | ||
| ```bash | ||
| ollama list | ||
| ``` | ||
|
|
||
| 2. **Pull the model:** | ||
| ```bash | ||
| ollama pull llama2 | ||
| ``` | ||
|
|
||
| 3. **Use a different model:** | ||
| ```bash | ||
| export CORTEX_MODEL=llama2 | ||
| ``` | ||
|
|
||
| ### Error: "Context length exceeded" | ||
|
|
||
| **Symptom:** | ||
| ``` | ||
| Error: This model's maximum context length is 4096 tokens | ||
| ``` | ||
|
|
||
| **Solutions:** | ||
|
|
||
| 1. **Simplify your request:** | ||
| ```bash | ||
| # Instead of | ||
| cortex install "complete development environment with..." | ||
|
|
||
| # Try | ||
| cortex install "python development tools" | ||
| ``` | ||
|
|
||
| 2. **Use a model with larger context:** | ||
| ```bash | ||
| export CORTEX_MODEL=claude-3-opus | ||
| ``` | ||
|
|
||
| --- |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for environment variable definitions and usage
rg -n 'CORTEX_PROVIDER|CORTEX_MODEL|CORTEX_MAX_CONTEXT' --type=py --type=sh --type=js --type=tsRepository: cortexlinux/Cortex
Length of output: 356
🏁 Script executed:
# Search for CLI command definitions in Python files
rg -n 'def (history|rollback|status|wizard)' --type=py -A 2Repository: cortexlinux/Cortex
Length of output: 1955
🏁 Script executed:
# Look for click/argparse command decorators
rg -n '@(app\.|click\.|command)' --type=py | head -30Repository: cortexlinux/Cortex
Length of output: 44
🏁 Script executed:
# Find main CLI entry points
find . -type f -name "*.py" -o -name "*.js" -o -name "*.ts" | xargs grep -l "click\|argparse\|commander" | head -20Repository: cortexlinux/Cortex
Length of output: 523
🏁 Script executed:
# Look at the cortex/cli.py file to understand which env vars are actually used
cat -n cortex/cli.py | sed -n '60,80p'Repository: cortexlinux/Cortex
Length of output: 1182
🏁 Script executed:
# Search for all CORTEX_ environment variables in the codebase
rg -n 'CORTEX_' --type=pyRepository: cortexlinux/Cortex
Length of output: 2950
🏁 Script executed:
# Check if CORTEX_MODEL is mentioned anywhere in the codebase
rg -n 'CORTEX_MODEL' -iRepository: cortexlinux/Cortex
Length of output: 586
Update environment variable documentation for accuracy.
The troubleshooting section references environment variables that don't exist or aren't implemented in the actual Cortex CLI:
CORTEX_PROVIDERis correctly implemented and documentedCORTEX_MODELandCORTEX_MAX_CONTEXTare not exposed as user-facing environment variables in the CLI code;CORTEX_MODELappears only in systemd service files as internal configuration
Remove or replace references to CORTEX_MODEL and CORTEX_MAX_CONTEXT in the troubleshooting guide. The CLI commands (history, rollback, status, wizard) are correctly documented.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
351-351: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
380-380: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
404-404: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/TROUBLESHOOTING.md around lines 346 to 424, the doc references
environment variables CORTEX_MODEL and CORTEX_MAX_CONTEXT that are not
user-facing in the CLI; remove those references and any example exports using
them, and either replace them with the supported CORTEX_PROVIDER variable or
reword to instruct users to configure the model/context via the actual
mechanisms (e.g., service configuration/systemd or the provider-specific config)
used by Cortex; ensure examples and solution steps no longer show "export
CORTEX_MODEL=..." or "export CORTEX_MAX_CONTEXT=..." and instead point to the
correct configuration approach or omit those environment-variable suggestions.
| 3. **Install Ollama if missing:** | ||
| ```bash | ||
| curl -fsSL https://ollama.ai/install.sh | sh | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
current Ollama installation URL Linux official documentation 2025
💡 Result:
Official Linux install docs: https://docs.ollama.com/linux [1]
Install script URL used there: https://ollama.com/install.sh [2]
Sources:
[1] Ollama — Linux documentation (docs.ollama.com/linux).
[2] Ollama — Download (ollama.com/download/linux).
Update Ollama installation URL to current official domain.
The installation URL at line 369 uses an outdated domain. Change https://ollama.ai/install.sh to https://ollama.com/install.sh per the current official Ollama documentation.
🤖 Prompt for AI Agents
In docs/TROUBLESHOOTING.md around lines 367 to 370, the Ollama install command
uses an outdated domain; update the URL from https://ollama.ai/install.sh to the
current official https://ollama.com/install.sh so the curl install line points
to the correct official installer.
Summary
Implements Issue #263: Common errors and solutions guide
This PR adds a comprehensive troubleshooting guide (
docs/TROUBLESHOOTING.md) to help users diagnose and fix common issues.Sections Covered
1. API Key Issues
2. Installation Errors
3. Network & Connectivity
4. Permission Problems
5. LLM Provider Issues
6. Package Manager Conflicts
7. Performance Issues
8. Rollback & Recovery
Additional Features
Test Plan
Files Changed
docs/TROUBLESHOOTING.md- New troubleshooting guide (588 lines)Closes #263
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.