Initial commit

skills/error-troubleshooter/references/common-error-patterns.md

@@ -0,0 +1,784 @@
+# Common Error Patterns and Quick Fixes
+
+This reference documents frequently encountered trivial errors and their known solutions. Use this for rapid diagnosis and resolution of common issues.
+
+## How to Use This Reference
+
+1. **Pattern Match**: Compare the error against patterns in this document
+2. **Apply Fix**: If there's a high-confidence match, apply the suggested fix
+3. **Verify**: Confirm the fix resolved the issue
+4. **Escalate**: If fix fails, revert and proceed to rigorous investigation
+
+**Important**: Only apply quick fixes when confident. If the first attempt doesn't work, revert and use systematic troubleshooting.
+
+## Python Common Errors
+
+### 1. ModuleNotFoundError / ImportError
+
+**Pattern:**
+```
+ModuleNotFoundError: No module named 'package_name'
+ImportError: cannot import name 'something' from 'package'
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Package Not Installed
+```bash
+# Fix
+pip install package_name
+
+# Or if using requirements.txt
+pip install -r requirements.txt
+```
+
+#### Cause 2: Wrong Python Environment
+```bash
+# Check current Python
+which python
+python --version
+
+# Activate correct virtual environment
+source venv/bin/activate  # Unix
+.\venv\Scripts\activate  # Windows
+
+# Or use python3 explicitly
+pip3 install package_name
+```
+
+#### Cause 3: Package Name Mismatch
+```bash
+# Install name might differ from import name
+# Example: pip install Pillow, but import PIL
+pip install Pillow  # for 'import PIL'
+pip install opencv-python  # for 'import cv2'
+pip install scikit-learn  # for 'import sklearn'
+```
+
+#### Cause 4: Circular Import
+- Check if files are importing each other
+- Restructure imports or use lazy imports
+
+### 2. SyntaxError
+
+**Pattern:**
+```
+SyntaxError: invalid syntax
+SyntaxError: unexpected EOF while parsing
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Missing Colon
+```python
+# Wrong
+if condition
+    do_something()
+
+# Right
+if condition:
+    do_something()
+```
+
+#### Cause 2: Unclosed Brackets/Quotes
+```python
+# Wrong
+result = calculate(x, y
+print("Hello world)
+
+# Right
+result = calculate(x, y)
+print("Hello world")
+```
+
+#### Cause 3: Python Version Incompatibility
+```python
+# f-strings require Python 3.6+
+print(f"Value: {x}")  # SyntaxError in Python 3.5
+
+# Walrus operator requires Python 3.8+
+if (n := len(items)) > 10:  # SyntaxError in Python 3.7
+```
+
+**Fix:** Check Python version and upgrade if needed
+
+### 3. IndentationError
+
+**Pattern:**
+```
+IndentationError: unexpected indent
+IndentationError: expected an indented block
+```
+
+**Common Causes & Fixes:**
+
+#### Cause: Mixed Tabs and Spaces
+```bash
+# Fix: Convert to spaces (recommended)
+# In most editors: Settings → Convert indentation to spaces
+
+# Or use autopep8
+pip install autopep8
+autopep8 --in-place --select=E101,E121 file.py
+```
+
+### 4. AttributeError
+
+**Pattern:**
+```
+AttributeError: 'NoneType' object has no attribute 'something'
+AttributeError: module 'X' has no attribute 'Y'
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: None Value
+```python
+# Function returned None when you expected object
+result = function_that_returns_none()
+result.method()  # AttributeError
+
+# Fix: Check for None
+if result is not None:
+    result.method()
+```
+
+#### Cause 2: Wrong Module Version
+```bash
+# API changed in new version
+pip show package_name  # Check version
+pip install package_name==1.2.3  # Install specific version
+```
+
+#### Cause 3: Module Not Reloaded
+```python
+# In interactive session/Jupyter
+import importlib
+importlib.reload(module_name)
+```
+
+### 5. FileNotFoundError
+
+**Pattern:**
+```
+FileNotFoundError: [Errno 2] No such file or directory: 'path/to/file'
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Wrong Current Directory
+```python
+# Check current directory
+import os
+print(os.getcwd())
+
+# Fix: Use absolute path or change directory
+os.chdir('/correct/path')
+# Or use absolute path
+file_path = os.path.join(os.path.dirname(__file__), 'data', 'file.txt')
+```
+
+#### Cause 2: Typo in Path
+- Check file name spelling (case-sensitive on Unix)
+- Check file extension
+
+#### Cause 3: File Doesn't Exist Yet
+```python
+# Create file if it doesn't exist
+os.makedirs(os.path.dirname(file_path), exist_ok=True)
+with open(file_path, 'w') as f:
+    f.write('')
+```
+
+## JavaScript/Node.js Common Errors
+
+### 1. Cannot find module
+
+**Pattern:**
+```
+Error: Cannot find module 'module-name'
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Module Not Installed
+```bash
+# Fix
+npm install module-name
+
+# Or restore all dependencies
+npm install
+```
+
+#### Cause 2: Wrong Node Version
+```bash
+# Check required version in package.json
+cat package.json | grep "engines"
+
+# Use nvm to switch version
+nvm install 16
+nvm use 16
+```
+
+#### Cause 3: Module Path Error
+```javascript
+// Wrong (relative path without ./)
+const myModule = require('utils/helper')
+
+// Right
+const myModule = require('./utils/helper')
+```
+
+### 2. Reference Error
+
+**Pattern:**
+```
+ReferenceError: X is not defined
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Variable Not Declared
+```javascript
+// Wrong
+console.log(myVar)  // ReferenceError
+
+// Right
+const myVar = 'value'
+console.log(myVar)
+```
+
+#### Cause 2: Scope Issue
+```javascript
+// Wrong
+if (true) {
+  var x = 1
+}
+console.log(x)  // Works with var, but not with let/const
+
+// Right
+let x
+if (true) {
+  x = 1
+}
+console.log(x)
+```
+
+#### Cause 3: Typo in Variable Name
+- Check spelling and case (JavaScript is case-sensitive)
+
+### 3. SyntaxError: Unexpected token
+
+**Pattern:**
+```
+SyntaxError: Unexpected token 'x'
+SyntaxError: Unexpected token {
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: JSON Parsing Error
+```javascript
+// Wrong: Invalid JSON
+const data = JSON.parse("{'key': 'value'}")  // Single quotes not valid JSON
+
+// Right: Valid JSON
+const data = JSON.parse('{"key": "value"}')
+```
+
+#### Cause 2: Missing Semicolons/Commas
+```javascript
+// Wrong
+const obj = {
+  key1: 'value1'
+  key2: 'value2'
+}
+
+// Right
+const obj = {
+  key1: 'value1',
+  key2: 'value2'
+}
+```
+
+#### Cause 3: ES6 Syntax in Old Node
+```javascript
+// Arrow functions require Node 4+
+const func = () => {}
+
+// async/await requires Node 7.6+
+async function test() { await promise }
+```
+
+**Fix:** Upgrade Node or use transpiler (Babel)
+
+### 4. ECONNREFUSED
+
+**Pattern:**
+```
+Error: connect ECONNREFUSED 127.0.0.1:3000
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Server Not Running
+```bash
+# Fix: Start the server
+npm start
+node server.js
+```
+
+#### Cause 2: Wrong Port
+```javascript
+// Check server port in code
+const PORT = process.env.PORT || 3000
+
+// Ensure client uses same port
+```
+
+#### Cause 3: Firewall Blocking
+```bash
+# Check if port is listening
+netstat -an | grep 3000  # Unix
+netstat -an | findstr 3000  # Windows
+```
+
+### 5. EADDRINUSE
+
+**Pattern:**
+```
+Error: listen EADDRINUSE: address already in use :::3000
+```
+
+**Common Causes & Fixes:**
+
+#### Fix 1: Kill Process Using Port
+```bash
+# Unix/Linux/Mac
+lsof -ti:3000 | xargs kill
+# Or
+kill $(lsof -t -i:3000)
+
+# Windows
+netstat -ano | findstr :3000
+taskkill /PID <PID> /F
+```
+
+#### Fix 2: Use Different Port
+```javascript
+const PORT = process.env.PORT || 3001  // Change port
+```
+
+## Git Common Errors
+
+### 1. Permission Denied (publickey)
+
+**Pattern:**
+```
+Permission denied (publickey).
+fatal: Could not read from remote repository.
+```
+
+**Common Causes & Fixes:**
+
+#### Cause: SSH Key Not Set Up
+```bash
+# Generate SSH key
+ssh-keygen -t ed25519 -C "your_email@example.com"
+
+# Add to SSH agent
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+
+# Copy public key and add to GitHub/GitLab
+cat ~/.ssh/id_ed25519.pub
+```
+
+### 2. Merge Conflict
+
+**Pattern:**
+```
+CONFLICT (content): Merge conflict in file.txt
+Automatic merge failed; fix conflicts and then commit the result.
+```
+
+**Common Causes & Fixes:**
+
+#### Standard Resolution
+```bash
+# 1. Open conflicted files and resolve markers
+# <<<<<<< HEAD
+# =======
+# >>>>>>> branch-name
+
+# 2. Stage resolved files
+git add file.txt
+
+# 3. Complete merge
+git commit
+```
+
+### 3. Detached HEAD
+
+**Pattern:**
+```
+You are in 'detached HEAD' state.
+```
+
+**Common Causes & Fixes:**
+
+#### Fix: Create Branch or Return to Branch
+```bash
+# Option 1: Create branch at current commit
+git checkout -b new-branch-name
+
+# Option 2: Return to main branch
+git checkout main
+```
+
+## Docker Common Errors
+
+### 1. Cannot connect to Docker daemon
+
+**Pattern:**
+```
+Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Docker Not Running
+```bash
+# Start Docker
+sudo systemctl start docker  # Linux
+# Or start Docker Desktop (Mac/Windows)
+```
+
+#### Cause 2: Permission Issue
+```bash
+# Add user to docker group
+sudo usermod -aG docker $USER
+# Then logout and login again
+```
+
+### 2. Port Already Allocated
+
+**Pattern:**
+```
+Error starting userland proxy: listen tcp 0.0.0.0:8080: bind: address already in use
+```
+
+**Common Causes & Fixes:**
+
+#### Fix 1: Stop Conflicting Container
+```bash
+# Find container using port
+docker ps | grep 8080
+
+# Stop it
+docker stop <container_id>
+```
+
+#### Fix 2: Use Different Port
+```bash
+# Change port mapping
+docker run -p 8081:8080 image_name
+```
+
+### 3. No Space Left on Device
+
+**Pattern:**
+```
+Error: No space left on device
+```
+
+**Common Causes & Fixes:**
+
+#### Fix: Clean Up Docker Resources
+```bash
+# Remove unused containers, images, volumes
+docker system prune -a --volumes
+
+# Or selectively
+docker container prune
+docker image prune -a
+docker volume prune
+```
+
+## Database Common Errors
+
+### 1. Connection Refused
+
+**Pattern:**
+```
+Error: connect ECONNREFUSED 127.0.0.1:5432
+psycopg2.OperationalError: could not connect to server: Connection refused
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Database Not Running
+```bash
+# PostgreSQL
+sudo systemctl start postgresql  # Linux
+brew services start postgresql  # Mac
+
+# MySQL
+sudo systemctl start mysql  # Linux
+brew services start mysql  # Mac
+
+# MongoDB
+sudo systemctl start mongod  # Linux
+brew services start mongodb-community  # Mac
+```
+
+#### Cause 2: Wrong Port
+- PostgreSQL default: 5432
+- MySQL default: 3306
+- MongoDB default: 27017
+
+#### Cause 3: Wrong Host
+```python
+# Wrong
+host='localhost'
+
+# Try
+host='127.0.0.1'
+# Or check actual host in database config
+```
+
+### 2. Authentication Failed
+
+**Pattern:**
+```
+Authentication failed for user 'username'
+Access denied for user 'username'@'localhost'
+```
+
+**Common Causes & Fixes:**
+
+#### Fix: Check Credentials
+```bash
+# PostgreSQL: Check user exists
+psql -U postgres
+\du  # List users
+
+# MySQL: Check user exists
+mysql -u root -p
+SELECT User, Host FROM mysql.user;
+
+# Reset password if needed
+ALTER USER 'username' IDENTIFIED BY 'new_password';
+```
+
+### 3. Database Does Not Exist
+
+**Pattern:**
+```
+FATAL: database "dbname" does not exist
+ERROR 1049 (42000): Unknown database 'dbname'
+```
+
+**Common Causes & Fixes:**
+
+#### Fix: Create Database
+```sql
+-- PostgreSQL
+CREATE DATABASE dbname;
+
+-- MySQL
+CREATE DATABASE dbname;
+
+-- Or use command line
+createdb dbname  # PostgreSQL
+mysql -e "CREATE DATABASE dbname"  # MySQL
+```
+
+## Package Manager Common Errors
+
+### 1. npm: EACCES Permission Denied
+
+**Pattern:**
+```
+npm ERR! code EACCES
+npm ERR! EACCES: permission denied
+```
+
+**Common Causes & Fixes:**
+
+#### Fix: Don't Use Sudo (Instead Fix Permissions)
+```bash
+# Fix npm global directory permissions
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
+source ~/.profile
+```
+
+### 2. pip: Could Not Find a Version
+
+**Pattern:**
+```
+ERROR: Could not find a version that satisfies the requirement package_name
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Typo in Package Name
+```bash
+# Fix: Check correct name on PyPI
+pip search package_name  # (Note: search disabled on PyPI)
+# Or search on https://pypi.org
+```
+
+#### Cause 2: Python Version Incompatibility
+```bash
+# Check Python version
+python --version
+
+# Some packages require specific Python versions
+# Upgrade Python or find compatible package version
+pip install package_name==1.2.3
+```
+
+#### Cause 3: No Internet / Proxy Issue
+```bash
+# Check connectivity
+ping pypi.org
+
+# If behind proxy
+pip install --proxy http://proxy:port package_name
+```
+
+### 3. Requirements File Error
+
+**Pattern:**
+```
+ERROR: Invalid requirement: 'package_name==1.0.0\r' (from line X of requirements.txt)
+```
+
+**Common Causes & Fixes:**
+
+#### Cause: Windows Line Endings
+```bash
+# Fix: Convert to Unix line endings
+dos2unix requirements.txt
+
+# Or with Python
+python -c "import sys; data = open('requirements.txt', 'r').read(); open('requirements.txt', 'w').write(data.replace('\r\n', '\n'))"
+```
+
+## Build Tool Common Errors
+
+### 1. Make: Command Not Found
+
+**Pattern:**
+```
+make: command not found
+```
+
+**Common Causes & Fixes:**
+
+#### Fix: Install Build Tools
+```bash
+# Debian/Ubuntu
+sudo apt-get install build-essential
+
+# macOS
+xcode-select --install
+
+# CentOS/RHEL
+sudo yum groupinstall "Development Tools"
+```
+
+### 2. Compiler Error: Missing Header
+
+**Pattern:**
+```
+fatal error: Python.h: No such file or directory
+fatal error: openssl/ssl.h: No such file or directory
+```
+
+**Common Causes & Fixes:**
+
+#### Fix: Install Development Headers
+```bash
+# Python headers
+sudo apt-get install python3-dev  # Debian/Ubuntu
+sudo yum install python3-devel  # CentOS/RHEL
+
+# OpenSSL headers
+sudo apt-get install libssl-dev  # Debian/Ubuntu
+sudo yum install openssl-devel  # CentOS/RHEL
+```
+
+## Cross-Platform Path Issues
+
+### Windows Backslash vs Unix Forward Slash
+
+**Pattern:**
+```
+FileNotFoundError: [Errno 2] No such file or directory: 'path\\to\\file'
+```
+
+**Common Causes & Fixes:**
+
+#### Fix: Use os.path or pathlib
+```python
+# Wrong (platform-specific)
+path = 'C:\\Users\\name\\file.txt'  # Windows only
+path = '/home/user/file.txt'  # Unix only
+
+# Right (cross-platform)
+import os
+path = os.path.join('Users', 'name', 'file.txt')
+
+# Or use pathlib (Python 3.4+)
+from pathlib import Path
+path = Path('Users') / 'name' / 'file.txt'
+```
+
+## Quick Diagnosis Checklist
+
+When encountering an error, quickly check:
+
+- [ ] Is the tool/service running?
+- [ ] Are dependencies installed?
+- [ ] Is it a typo (file name, variable, import)?
+- [ ] Am I in the right directory?
+- [ ] Am I using the right version (Python, Node, package)?
+- [ ] Am I in the right environment (virtual env, conda env)?
+- [ ] Is there a port conflict?
+- [ ] Do I have proper permissions?
+- [ ] Are there network/firewall issues?
+- [ ] Did I check the error message carefully?
+
+## Adding New Patterns
+
+As new common errors are discovered during troubleshooting:
+
+1. **Document the pattern**: Error message template
+2. **Document the cause**: Why it happens
+3. **Document the fix**: Step-by-step solution
+4. **Test the fix**: Verify it works reliably
+5. **Add to this file**: So it's available for future use
+
+**Format:**
+```markdown
+### N. Brief Error Description
+
+**Pattern:**
+```
+Error message pattern
+```
+
+**Common Causes & Fixes:**
+
+#### Cause 1: Specific Cause
+```bash
+# Fix
+command or code to fix
+```
+
+**Notes:** Additional context or warnings
+```