From 114508ea6739b4eb34573078805b5298106cbf8e Mon Sep 17 00:00:00 2001 From: Chandrahas Maddineni Date: Thu, 11 Dec 2025 21:56:31 -0500 Subject: [PATCH 1/2] docs: add troubleshooting guide (fixes #263) --- docs/TROUBLESHOOTING.md | 283 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 docs/TROUBLESHOOTING.md diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..b342ad9 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,283 @@ +# 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 +``` + +### 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 From d266c93a81365e648f33991476748ebe3f9da964 Mon Sep 17 00:00:00 2001 From: Chandrahas Maddineni Date: Thu, 11 Dec 2025 22:55:04 -0500 Subject: [PATCH 2/2] docs: resolve all code review feedback (security, safety, formatting) --- docs/TROUBLESHOOTING.md | 80 +++++++++++++++++++++++++++-------------- 1 file changed, 54 insertions(+), 26 deletions(-) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index b342ad9..8c32d5f 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -20,7 +20,7 @@ Common errors and solutions for Cortex Linux. ### Error: "No API key found" **Symptom:** -``` +```text Error: No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable. ``` @@ -29,15 +29,15 @@ Error: No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment var 1. **Set the environment variable:** ```bash # For Claude (recommended) -export ANTHROPIC_API_KEY='sk-ant-api03-your-key-here' +export ANTHROPIC_API_KEY='' # For OpenAI -export OPENAI_API_KEY='sk-your-key-here' +export OPENAI_API_KEY='' ``` 2. **Add to shell config for persistence:** ```bash -echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key"' >> ~/.bashrc +echo 'export ANTHROPIC_API_KEY=""' >> ~/.bashrc source ~/.bashrc ``` @@ -46,7 +46,8 @@ source ~/.bashrc cortex wizard ``` -4. **For offline mode (no API key needed):** +4. **For Local Provider mode (No API key needed):** + *Note: Installation of tools like Docker may still require an internet connection.* ```bash export CORTEX_PROVIDER=ollama cortex install docker @@ -55,7 +56,7 @@ cortex install docker ### Error: "API rate limit exceeded" **Symptom:** -``` +```text Error: Rate limit exceeded. Please wait before trying again. ``` @@ -70,14 +71,14 @@ sleep 60 && cortex install docker export CORTEX_PROVIDER=ollama ``` ------ +--- ## Installation Errors ### Error: "Package not found" **Symptom:** -``` +```text E: Unable to locate package xyz ``` @@ -107,10 +108,11 @@ sudo apt --fix-broken install sudo apt update && sudo apt upgrade ``` + ### Error: "dpkg lock" **Symptom:** -``` +```text E: Could not get lock /var/lib/dpkg/lock-frontend ``` @@ -121,18 +123,26 @@ E: Could not get lock /var/lib/dpkg/lock-frontend sudo lsof /var/lib/dpkg/lock-frontend ``` -2. **Kill stuck apt process (use with caution):** +2. **If it's genuinely stuck, stop the specific process (use with caution):** ```bash -sudo killall apt apt-get +# Check for apt, apt-get, or unattended-upgrades +ps aux | egrep 'apt|apt-get|unattended' | egrep -v egrep + +# Then (only if needed) kill the specific PID (replace ): +sudo kill + +# Recovery: Run these if the package manager breaks after killing the process +sudo dpkg --configure -a +sudo apt --fix-broken install ``` ------ +--- ## Network & Connectivity ### Error: "Could not resolve host" **Symptom:** -``` +```text Could not resolve 'archive.ubuntu.com' ``` @@ -143,11 +153,17 @@ Could not resolve 'archive.ubuntu.com' ping -c 3 8.8.8.8 ``` -2. **Try different DNS (Safe Method):** +2. **Try different DNS (Temporary):** + *Note: `/etc/resolv.conf` is often overwritten. Use `resolvectl` for permanent changes.* ```bash +# Append Google DNS echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf + +# Rollback (Undo): Edit the file and remove the line +sudo nano /etc/resolv.conf ``` + ### Error: "SSL certificate problem" **Solutions:** @@ -163,7 +179,7 @@ sudo update-ca-certificates timedatectl status sudo timedatectl set-ntp true ``` ------ +--- ## Permission Problems @@ -181,25 +197,35 @@ sudo cortex install docker --execute ls -la ~/.cortex/ ``` ------ +--- ## LLM Provider Issues ### Error: "Ollama not running" **Symptom:** -``` +```text Error: Could not connect to Ollama at localhost:11434 -``` +```` **Solutions:** -1. **Start Ollama:** +1. **Start System Service (Recommended):** + +```bash +sudo systemctl start ollama +``` + +2. **Manual Start (Fallback):** + *Note: Only use this if the system service is unavailable.* + ```bash -ollama serve & +ollama serve ``` -2. **Install Ollama if missing:** +3. **Install Ollama if missing:** + *Note: Always review remote scripts before running them.* + ```bash curl -fsSL https://ollama.com/install.sh | sh ``` @@ -207,7 +233,8 @@ curl -fsSL https://ollama.com/install.sh | sh ### Error: "Context length exceeded" **Symptom:** -``` + +```text Error: This model's maximum context length is 4096 tokens ``` @@ -218,17 +245,18 @@ Error: This model's maximum context length is 4096 tokens 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:** -``` +```text error: cannot install "firefox": classic confinement requires snaps ``` @@ -238,7 +266,7 @@ error: cannot install "firefox": classic confinement requires snaps ```bash sudo snap install firefox --classic ``` ------ +--- ## Performance Issues @@ -255,7 +283,7 @@ export CORTEX_PROVIDER=ollama ```bash ping api.anthropic.com ``` ------ +--- ## Rollback & Recovery