orion/docs/development/troubleshooting.md

# PyCharm Troubleshooting Guide

Common PyCharm issues and their solutions for the development team.

---

## Table of Contents

- [Go to Declaration Not Working (Ctrl+B)](#go-to-declaration-not-working-ctrlb)
- [Import Errors and Red Underlines](#import-errors-and-red-underlines)
- [Python Interpreter Issues](#python-interpreter-issues)
- [Debugging Not Working](#debugging-not-working)
- [Performance Issues](#performance-issues)
- [Git Integration Issues](#git-integration-issues)
- [Database Tool Issues](#database-tool-issues)

---

## Go to Declaration Not Working (Ctrl+B)

### Problem

When you press **Ctrl+B** (or Cmd+B on Mac) on a function, class, or variable, PyCharm shows:
- "Cannot find declaration to go to"
- No navigation occurs
- Imports are marked as unresolved even though code runs fine

**Example:**
```python
from app.services.admin_audit_service import admin_audit_service

# Ctrl+B on get_audit_logs doesn't work
logs = admin_audit_service.get_audit_logs(db, filters)
```

### Solution 1: Configure Source Roots (Most Common Fix)

PyCharm needs to know your project structure:

1. **Mark project root as Sources Root:**
   - Right-click on project root folder (`letzshop-product-import`)
   - Select **"Mark Directory as"** → **"Sources Root"**
   - The folder icon should turn blue

2. **Via Project Structure settings:**
   - **File** → **Settings** (Ctrl+Alt+S)
   - Navigate to **Project: letzshop-product-import** → **Project Structure**
   - Select your project root directory
   - Click the **"Sources"** button at the top
   - Click **Apply** → **OK**

3. **Verify the change:**
   - Your project root should now have a blue folder icon
   - The `.idea` folder should show the source root is configured

### Solution 2: Verify Python Interpreter

Ensure PyCharm is using the correct virtual environment:

1. **Check current interpreter:**
   - **File** → **Settings** → **Project** → **Python Interpreter**
   - Should show: `/home/samir/PycharmProjects/letzshop-product-import/.venv/bin/python`

2. **If wrong interpreter:**
   - Click the gear icon → **Add**
   - Select **"Existing environment"**
   - Navigate to: `[PROJECT_ROOT]/.venv/bin/python`
   - Click **OK**

3. **Wait for indexing:**
   - Bottom right corner will show "Indexing..."
   - Wait for it to complete before testing

### Solution 3: Invalidate Caches

PyCharm's index might be corrupted:

1. **File** → **Invalidate Caches...**
2. Select all checkboxes:
   - ✅ Invalidate and Restart
   - ✅ Clear file system cache and Local History
   - ✅ Clear downloaded shared indexes
3. Click **"Invalidate and Restart"**
4. **Wait 2-5 minutes** for re-indexing after restart

### Solution 4: Reimport Project

If nothing else works, rebuild the project structure:

1. **Close PyCharm**
2. **Delete PyCharm's cache folder:**
   ```bash
   rm -rf .idea/
   ```
3. **Reopen project in PyCharm:**
   - **File** → **Open**
   - Select project folder
   - Let PyCharm recreate `.idea/` folder
4. **Reconfigure:**
   - Set Python interpreter
   - Mark source roots
   - Wait for indexing

### Solution 5: Check .idea/workspace.xml

Sometimes workspace configuration gets corrupted:

```bash
# Close PyCharm first
rm .idea/workspace.xml
# Reopen PyCharm - it will regenerate this file
```

---

## Import Errors and Red Underlines

### Problem

Imports show red underlines and errors like:
- "Unresolved reference"
- "No module named 'app'"
- Code runs fine but PyCharm shows errors

### Solution

1. **Check Sources Root** (see above)

2. **Verify `__init__.py` files exist:**
   ```bash
   # All package directories need __init__.py
   ls -la app/__init__.py
   ls -la app/services/__init__.py
   ls -la app/api/__init__.py
   ```

3. **Add project root to PYTHONPATH:**
   - **File** → **Settings** → **Project** → **Project Structure**
   - Right-click project root → **"Mark as Sources Root"**

4. **Enable namespace packages** (if using PEP 420):
   - **File** → **Settings** → **Editor** → **Code Style** → **Python**
   - Check "Support namespace packages"

---

## Python Interpreter Issues

### Problem

- "No Python interpreter configured"
- Wrong Python version
- Missing packages even though they're installed

### Solution

1. **Verify virtual environment:**
   ```bash
   # In terminal
   which python  # Should show .venv/bin/python
   python --version  # Should show Python 3.13.x
   ```

2. **Configure in PyCharm:**
   - **File** → **Settings** → **Project** → **Python Interpreter**
   - Click gear icon → **Add**
   - Select **"Existing Environment"**
   - Choose: `[PROJECT_ROOT]/.venv/bin/python`

3. **Refresh interpreter packages:**
   - In Python Interpreter settings
   - Click refresh icon (⟳)
   - Wait for packages to reload

4. **Reinstall packages if needed:**
   ```bash
   source .venv/bin/activate
   pip install -r requirements.txt
   pip install -r requirements-dev.txt
   ```

---

## Debugging Not Working

### Problem

- Breakpoints are grayed out
- Debugger doesn't stop at breakpoints
- "Debugger is not attached"

### Solution 1: Check Run Configuration

1. **Edit configuration:**
   - Top right → Edit Configurations
   - Should use "Python" configuration type
   - Script path should point to your main file
   - Interpreter should be your virtual environment

2. **For FastAPI/Uvicorn:**
   - Module: `uvicorn`
   - Parameters: `main:app --reload`
   - Working directory: Project root

### Solution 2: Enable Gevent/Asyncio Support

For async code (FastAPI):

1. **File** → **Settings** → **Build, Execution, Deployment** → **Python Debugger**
2. Check **"Gevent compatible"** or **"Asyncio compatible"**
3. Restart debugger

### Solution 3: Check Breakpoint Settings

Right-click on breakpoint (red dot):
- Ensure "Enabled" is checked
- Check "Suspend" is set to "All"
- Remove any conditions if not needed

---

## Performance Issues

### Problem

- PyCharm is slow or freezing
- High CPU/memory usage
- Indexing takes forever

### Solution 1: Exclude Unnecessary Directories

Exclude directories PyCharm doesn't need to index:

1. **File** → **Settings** → **Project** → **Project Structure**
2. **Mark as "Excluded":**
   - `.venv` (if not already)
   - `node_modules`
   - `.pytest_cache`
   - `__pycache__`
   - `htmlcov`
   - `site` (mkdocs build output)

3. **Right-click these folders in Project view:**
   - **Mark Directory as** → **Excluded**

### Solution 2: Increase Memory

1. **Help** → **Change Memory Settings**
2. Increase heap size to **2048 MB** or higher
3. Restart PyCharm

### Solution 3: Disable Unused Plugins

1. **File** → **Settings** → **Plugins**
2. Disable plugins you don't use
3. Keep essential: Python, Git, Database, Markdown
4. Restart PyCharm

### Solution 4: Pause Indexing

If you need to work immediately:

1. **File** → **Pause Indexing**
2. Do your work
3. **Resume Indexing** when convenient

---

## Git Integration Issues

### Problem

- Git operations fail
- "Cannot run git" errors
- Changes not detected

### Solution 1: Configure Git Executable

1. **File** → **Settings** → **Version Control** → **Git**
2. **Path to Git executable:**
   - Linux/Mac: `/usr/bin/git`
   - Windows: `C:\Program Files\Git\bin\git.exe`
3. Click **"Test"** to verify
4. Click **OK**

### Solution 2: Check Git Root

1. **File** → **Settings** → **Version Control**
2. Verify your project root is listed
3. If missing, click **+** and add it

### Solution 3: Refresh VCS

1. **VCS** → **Refresh File Status**
2. Or: **Git** → **Refresh**
3. Or press: **Ctrl+F5**

---

## Database Tool Issues

### Problem

- Can't connect to PostgreSQL database
- "Connection refused" errors
- Tables not showing

### Solution 1: Verify Database Connection

1. **Database** tool window (usually right side)
2. Click **+** → **Data Source** → **PostgreSQL**
3. **Configure:**
   ```
   Host: localhost
   Port: 5432
   Database: letzshop_db
   User: [from .env file]
   Password: [from .env file]
   ```
4. Click **"Test Connection"**
5. Download drivers if prompted

### Solution 2: Check Database is Running

```bash
# Check if PostgreSQL is running
sudo systemctl status postgresql

# Start if not running
sudo systemctl start postgresql
```

### Solution 3: Verify .env Configuration

```bash
# Check your .env file
cat .env | grep DATABASE

# Should show something like:
DATABASE_URL=postgresql://user:password@localhost:5432/letzshop_db
```

---

## Quick Checklist for New Developers

When setting up PyCharm for the first time:

- [ ] Clone repository
- [ ] Create virtual environment: `python -m venv .venv`
- [ ] Activate: `source .venv/bin/activate`
- [ ] Install dependencies: `pip install -r requirements.txt`
- [ ] Open project in PyCharm
- [ ] Configure Python interpreter (`.venv/bin/python`)
- [ ] Mark project root as Sources Root
- [ ] Exclude `.venv`, `.pytest_cache`, `__pycache__` directories
- [ ] Configure Git executable
- [ ] Configure database connection
- [ ] Wait for indexing to complete
- [ ] Test: Ctrl+B on an import should work

---

## Still Having Issues?

### Check PyCharm Logs

1. **Help** → **Show Log in Explorer/Finder**
2. Look for errors in `idea.log`
3. Search for "ERROR" or "Exception"

### Enable Debug Logging

1. **Help** → **Diagnostic Tools** → **Debug Log Settings**
2. Add: `#com.intellij.python`
3. Reproduce the issue
4. Check logs

### Report to Team

If the issue persists:

1. Screenshot the error
2. Share PyCharm version: **Help** → **About**
3. Share Python version: `python --version`
4. Share OS: `uname -a` (Linux/Mac) or `ver` (Windows)
5. Post in team chat with:
   - What you were trying to do
   - What error you got
   - What you've tried so far

---

## Related Documentation

- [PyCharm Make Configuration](pycharm-configuration-make.md) - Configure Make with virtual environment
- [Contributing Guide](contributing.md) - Development workflow
- [Database Migrations](database-migrations.md) - Working with Alembic