Skip to content

Troubleshooting Import Errors

Common Import Issues and Solutions

Issue: "ModuleNotFoundError: No module named 'loan_defenders_models'" or 'loan_defenders_utils'

Symptoms: - IDE shows red squiggly lines under imports - Code runs but IDE reports errors - "ModuleNotFoundError" when running Python scripts

Root Cause: The shared packages (loan_defenders_models, loan_defenders_utils) are now at the repository root and should be automatically discovered by uv's workspace configuration.

Solution (for local development):

  1. Verify workspace sync: 

    # From repository root
uv sync

  2. If imports still fail, check PYTHONPATH: 

    export PYTHONPATH="${PWD}:${PYTHONPATH}"

  3. For IDE issues, reload the Python interpreter in your IDE to pick up the new paths.

Why This Happens: After restructuring from apps/shared/ to root-level packages, some environments may still reference old paths.

Verification: 

# Test imports work
uv run python -c "from loan_defenders_models import LoanApplication; print('✓ Models work')"
uv run python -c "from loan_defenders_utils import Observability; print('✓ Utils work')"

Issue: Stale Imports or "AttributeError" on Existing Functions

Symptoms: - Code changes don't take effect - "AttributeError" for functions that exist in source - Import errors after restructuring code

Root Cause: Python caches compiled bytecode (.pyc files) in __pycache__/ directories. After moving or renaming files, stale cache can cause import issues.

Solution: Clear all Python bytecode cache: 

# From repository root
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -type f -name "*.pyc" -delete 2>/dev/null

When to Clear Cache: - After restructuring packages - After renaming modules - After changing import paths - When seeing mysterious import or attribute errors

Prevention: Add to .env or shell profile: 

export PYTHONDONTWRITEBYTECODE=1

Issue: IDE Shows Import Errors but Code Runs Fine

Symptoms: - Red squiggly lines in IDE - Code runs successfully with uv run or python - IDE autocomplete doesn't work

Root Cause: IDE's Python language server hasn't detected the updated sys.path from .pth files.

Solution: 1. Reload IDE Window: - VS Code: Cmd/Ctrl + Shift + P → "Developer: Reload Window"

  1. Restart Python Language Server:

  2. VS Code: Cmd/Ctrl + Shift + P → "Python: Restart Language Server"

  3. Select Correct Python Interpreter:

  4. VS Code: Click Python version in status bar → Select .venv/bin/python

  5. Last Resort - Reinstall Workspace: 

    uv sync --reinstall
./scripts/fix_imports.sh

Understanding .PTH Files

What Are .PTH Files?

.pth (path configuration) files tell Python to add directories to sys.path when the interpreter starts.

Location: .venv/lib/python3.11/site-packages/
Format: Plain text, one path per line
Purpose: Extend Python import search paths

Example: 

# Contents of a .pth file
/workspaces/loan-defenders

Is This Best Practice?

✅ YES for Development: - Standard practice for editable installs (pip install -e .) - Used by all major Python tools (pip, setuptools, poetry, uv) - Enables code changes without reinstalling packages - Perfect for monorepos with shared packages

❌ NO for Production: - Production should use proper pip install (not editable) - Docker images should have packages installed normally - .pth files are development-time conveniences

How Loan Defenders Uses Workspace Packages

Current Package Structure (Post-Refactoring): 

loan_defenders_models/  # Shared business models (root level)
loan_defenders_utils/   # Shared utilities (root level)
apps/
  api/                  # API service
  mcp_servers/          # MCP tool servers

UV Workspace Configuration: 

# pyproject.toml
[tool.uv.workspace]
members = [
    "apps/api",
    "loan_defenders_models",
    "loan_defenders_utils",
    ...
]

What UV Manages: UV handles all imports automatically through its workspace configuration. Packages at the root are directly importable:

from loan_defenders_models import LoanApplication  # ✓ Works!
from loan_defenders_utils import Observability     # ✓ Works!

Quick Reference

Check Current Python Path

.venv/bin/python -c "import sys; print('\\n'.join(sys.path))"

Test Imports

# Test models
.venv/bin/python -c "from loan_defenders_models import LoanApplication; print('✓')"

# Test utils
.venv/bin/python -c "from loan_defenders_utils import Observability; print('✓')"

# Test API
.venv/bin/python -c "from loan_defenders.api.app import app; print('✓')"

Fix All Import Issues

# Clear cache
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -type f -name "*.pyc" -delete 2>/dev/null

# Fix .pth files
./scripts/fix_imports.sh

# Reload IDE
# VS Code: Cmd/Ctrl + Shift + P → "Developer: Reload Window"