# Troubleshooting: Django Errors

[← Back to main skill](../SKILL.md)

---

## Issue: `django-admin: command not found` {#django-admin}

**After installing Django, command doesn't work**

### Solutions:

**Ensure venv is activated:**
```bash
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows
```

**Use `python -m django` instead:**
```bash
python -m django --version
python -m django startproject myproject
```

**Check Django is installed:**
```bash
pip list | grep Django
# or
pip show Django
```

**Reinstall Django:**
```bash
pip install --force-reinstall Django
```

---

## Issue: Port 8000 Already in Use {#port-in-use}

**Error:**
```
Error: That port is already in use.
```

### Solutions:

**Use different port:**
```bash
python manage.py runserver 8001
python manage.py runserver 0.0.0.0:8080
```

**Kill process using port 8000:**

**macOS/Linux:**
```bash
lsof -ti:8000 | xargs kill -9
```

**Windows (PowerShell):**
```powershell
netstat -ano | findstr :8000
# Note the PID, then:
taskkill /PID <pid> /F
```

**Windows (Command Prompt):**
```cmd
FOR /F "tokens=5" %P IN ('netstat -ano ^| findstr :8000') DO TaskKill /PID %P /F
```

---

## Issue: `ModuleNotFoundError: No module named 'django'`

**Django installed but Python can't find it**

### Solutions:

**Verify venv is activated:**
```bash
which python  # Should point to venv/bin/python
echo $VIRTUAL_ENV  # Should show venv path
```

**Check Django installation:**
```bash
pip list
pip show Django
```

**Install Django in venv:**
```bash
source venv/bin/activate
pip install Django
```

**Check you're using venv Python:**
```bash
python --version
which python
```

---

## Issue: `django.core.exceptions.ImproperlyConfigured`

**Common misconfigurations**

### `SECRET_KEY` not set

**Error:**
```
ImproperlyConfigured: The SECRET_KEY setting must not be empty.
```

**Solution:**
- Don't delete SECRET_KEY from settings.py
- If using environment variables, ensure .env file exists

### Database configuration error

**Error:**
```
ImproperlyConfigured: settings.DATABASES is improperly configured
```

**Solution - Check database settings:**
```python
# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}
```

---

## Issue: Migrations Not Applying

**Error:**
```
django.db.utils.OperationalError: no such table
```

### Solutions:

**Run migrations:**
```bash
python manage.py migrate
```

**Check migration files exist:**
```bash
ls */migrations/
# Should see 0001_initial.py files
```

**Reset database (development only!):**
```bash
rm db.sqlite3
python manage.py migrate
```

**Make migrations if they don't exist:**
```bash
python manage.py makemigrations
python manage.py migrate
```

---

## Issue: Static Files Not Loading

**CSS/JS files show 404 in browser**

### Solutions:

**Run collectstatic:**
```bash
python manage.py collectstatic
```

**Check STATIC_URL in settings.py:**
```python
STATIC_URL = '/static/'
```

**For development, ensure DEBUG=True:**
```python
DEBUG = True
```

**Check INSTALLED_APPS includes:**
```python
INSTALLED_APPS = [
    ...
    'django.contrib.staticfiles',
]
```

---

## Issue: Template Not Found

**Error:**
```
TemplateDoesNotExist at /path/
```

### Solutions:

**Check template path:**
```python
# settings.py
TEMPLATES = [
    {
        'DIRS': [BASE_DIR / 'templates'],  # Add this
        ...
    },
]
```

**Create templates directory:**
```bash
mkdir -p templates
```

**Check template name matches:**
```python
# views.py
return render(request, 'index.html')  # Must match file name exactly
```

---

## Issue: ALLOWED_HOSTS Error in Production

**Error:**
```
Invalid HTTP_HOST header: 'yourdomain.com'. You may need to add 'yourdomain.com' to ALLOWED_HOSTS.
```

### Solution:

**Add domain to ALLOWED_HOSTS:**
```python
# settings.py
DEBUG = False  # In production
ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']
```

**For development:**
```python
DEBUG = True
ALLOWED_HOSTS = []  # Empty list allows localhost automatically
```

---

## Issue: CSRF Verification Failed

**Error:**
```
Forbidden (403)
CSRF verification failed. Request aborted.
```

### Solutions:

**Ensure CSRF middleware is enabled:**
```python
# settings.py
MIDDLEWARE = [
    ...
    'django.middleware.csrf.CsrfViewMiddleware',
    ...
]
```

**Include CSRF token in forms:**
```html
<form method="post">
    {% csrf_token %}
    ...
</form>
```

**For AJAX, include CSRF token in headers:**
```javascript
// Get CSRF token from cookie
const csrftoken = document.querySelector('[name=csrfmiddlewaretoken]').value;

fetch('/api/endpoint/', {
    method: 'POST',
    headers: {
        'X-CSRFToken': csrftoken
    }
})
```

---

## Issue: Admin Interface Not Working

**Can't access /admin/**

### Solutions:

**Run migrations:**
```bash
python manage.py migrate
```

**Create superuser:**
```bash
python manage.py createsuperuser
```

**Check URL configuration:**
```python
# urls.py
from django.contrib import admin

urlpatterns = [
    path('admin/', admin.site.urls),
]
```

**Ensure admin app is installed:**
```python
# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
]
```

---

## Issue: Project Won't Start After Renaming

**Renamed project but errors occur**

### Solution:

**Update references in these files:**

**manage.py:**
```python
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'new_name.settings')
```

**asgi.py:**
```python
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'new_name.settings')
```

**wsgi.py:**
```python
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'new_name.settings')
```

**Rename project directory itself**

---

## Issue: Circular Import Errors

**Error:**
```
ImportError: cannot import name 'X' from partially initialized module 'Y'
```

### Solutions:

**Avoid circular imports:**
```python
# ❌ Bad - circular import
# models.py
from .views import something

# views.py
from .models import Model
```

**Use lazy imports:**
```python
# ✅ Good - import inside function
def my_view(request):
    from .models import Model  # Import here
    ...
```

**Or use Django's get_model:**
```python
from django.apps import apps
Model = apps.get_model('app_name', 'ModelName')
```

---

## Issue: `SyntaxError` in settings.py

**Error:**
```
SyntaxError: invalid syntax
```

### Solutions:

**Check Python version:**
```bash
python --version  # Should be 3.8+
```

**Look for common syntax errors:**
```python
# ❌ Missing comma
INSTALLED_APPS = [
    'django.contrib.admin'  # Missing comma!
    'django.contrib.auth',
]

# ✅ Correct
INSTALLED_APPS = [
    'django.contrib.admin',  # Comma here
    'django.contrib.auth',
]
```

**Validate Python syntax:**
```bash
python -m py_compile backend/settings.py
```

---

## Quick Diagnostic Commands

**Check Django installation:**
```bash
python -m django --version
```

**Check Python version:**
```bash
python --version
```

**Run system checks:**
```bash
python manage.py check
python manage.py check --deploy
```

**List installed packages:**
```bash
pip list
```

**Check migrations status:**
```bash
python manage.py showmigrations
```

**Test database connection:**
```bash
python manage.py dbshell
```

---

[← Back to django-project-setup](../SKILL.md)