sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d947fa5ca04fd1fee48ab79b3dec53527632b838
orion/docs/development/troubleshooting.md

9.8 KiB
Raw Blame History

PyCharm Troubleshooting Guide

Common PyCharm issues and their solutions for the development team.

Table of Contents

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

# 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

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

Reference in New Issue View Git Blame Copy Permalink