gh-iciakky-cc-general-skills/skills/error-troubleshooter/references/common-error-patterns.md

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

# Fix
pip install package_name

# Or if using requirements.txt
pip install -r requirements.txt

Cause 2: Wrong Python Environment

# 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

# 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

# Wrong
if condition
    do_something()

# Right
if condition:
    do_something()

Cause 2: Unclosed Brackets/Quotes

# Wrong
result = calculate(x, y
print("Hello world)

# Right
result = calculate(x, y)
print("Hello world")

Cause 3: Python Version Incompatibility

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Fix
npm install module-name

# Or restore all dependencies
npm install

Cause 2: Wrong Node Version

# 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

// 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

// Wrong
console.log(myVar)  // ReferenceError

// Right
const myVar = 'value'
console.log(myVar)

Cause 2: Scope Issue

// 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

// 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

// Wrong
const obj = {
  key1: 'value1'
  key2: 'value2'
}

// Right
const obj = {
  key1: 'value1',
  key2: 'value2'
}

Cause 3: ES6 Syntax in Old Node

// 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

# Fix: Start the server
npm start
node server.js

Cause 2: Wrong Port

// Check server port in code
const PORT = process.env.PORT || 3000

// Ensure client uses same port

Cause 3: Firewall Blocking

# 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

# 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

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

# 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

# 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

# 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

# Start Docker
sudo systemctl start docker  # Linux
# Or start Docker Desktop (Mac/Windows)

Cause 2: Permission Issue

# 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

# Find container using port
docker ps | grep 8080

# Stop it
docker stop <container_id>

Fix 2: Use Different Port

# 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

# 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

# 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

# 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

# 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

-- 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)

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

### 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