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)
• Import Errors and Red Underlines
• Python Interpreter Issues
• Debugging Not Working
• Performance Issues
• Git Integration Issues
• Database Tool Issues
• Frontend Asset Loading 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:

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:

   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:

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

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

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

   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: wizamart_db
   User: [from .env file]
   Password: [from .env file]
   

4. Click "Test Connection"
5. Download drivers if prompted

Solution 2: Check Database is Running

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Start if not running
sudo systemctl start postgresql

Solution 3: Verify .env Configuration

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

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

---

Frontend Asset Loading Issues

Problem

• Tailwind CSS styles not loading
• Alpine.js not initializing
• Frontend pages look unstyled
• Console errors about missing CSS/JS files
• App doesn't work offline

Solution 1: Verify CDN Fallback Files Exist

All frontends use CDN with local fallback. Check that local copies exist:

# From project root
ls -lh static/shared/css/tailwind.min.css
ls -lh static/shared/js/vendor/alpine.min.js

Expected output:

-rw-r--r-- 1 user user 2.9M static/shared/css/tailwind.min.css
-rw-r--r-- 1 user user  44K static/shared/js/vendor/alpine.min.js

If files are missing:

# Download Tailwind CSS
cd static/shared/css
curl -o tailwind.min.css https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css

# Download Alpine.js
cd ../js/vendor
curl -o alpine.min.js https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js

Solution 2: Check Browser Console

Open DevTools (F12) and check the Console tab for errors:

Common errors:

• GET http://localhost:8000/static/shared/css/tailwind.min.css [404 Not Found] → File missing
• Alpine.js CDN failed, loading local copy... → Normal fallback behavior
• Uncaught ReferenceError: Alpine is not defined → Alpine.js failed to load

Solution 3: Test CDN Fallback Behavior

To verify fallback works correctly:

1. Start application:

   uvicorn app.main:app --reload
   

2. Test with CDN blocked:

   • Open browser DevTools (F12)
   • Go to Network tab
   • Add request blocking rule for cdn.jsdelivr.net
   • Reload page

3. Verify fallback:

   • Check Console for: ⚠️ Alpine.js CDN failed, loading local copy...
   • Check Network tab shows local files loaded
   • Page should still work normally

Solution 4: Verify Static Files Mounting

Check that FastAPI is serving static files correctly:

In app/main.py:

from fastapi.staticfiles import StaticFiles

app.mount("/static", StaticFiles(directory="static"), name="static")

Test static file serving:

# With app running, test directly:
curl http://localhost:8000/static/shared/css/tailwind.min.css | head -n 5
curl http://localhost:8000/static/shared/js/vendor/alpine.min.js | head -n 5

Solution 5: File Permissions

If files exist but return 403 Forbidden:

# Fix permissions
chmod 644 static/shared/css/tailwind.min.css
chmod 644 static/shared/js/vendor/alpine.min.js
chmod 755 static/shared/css
chmod 755 static/shared/js/vendor

Solution 6: For Offline Development

If working completely offline, the CDN will always fail. Verify:

1. Console shows fallback message (expected behavior)
2. Local files load successfully
3. Page functions normally

To suppress CDN warnings when offline:

• Accept that CDN will fail (expected)
• Fallback mechanism handles it automatically
• Or modify templates to use local-only (see CDN Fallback Strategy)

Solution 7: Network Issues

If both CDN and local files fail intermittently:

1. Check browser cache:

   • Open DevTools → Network tab
   • Check "Disable cache" option
   • Hard reload: Ctrl+Shift+R

2. Clear browser cache completely:

   • Browser Settings → Privacy → Clear browsing data
   • Select "Cached images and files"
   • Clear data

3. Check for firewall/proxy issues:

   # Test CDN accessibility
   curl https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css | head -n 5
   

Related Documentation

See CDN Fallback Strategy for complete details on:

• How the fallback mechanism works
• Updating local asset files
• Production deployment considerations
• Air-gapped deployment setup

---

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 - Configure Make with virtual environment
• Contributing Guide - Development workflow
• Database Migrations - Working with Alembic