---
name: 500-error-eliminator
description: Систематическая диагностика и устранение Django 500 Internal Server Error через анализ кода, конфигурации, шаблонов и логов. Используй когда пользователь сообщает о 500 ошибке, «Internal Server Error», падении сервера, «сайт упал», «500 на проде», или просит отладить ошибку в Django-приложении (dev или production). Для общего системного дебага не-Django багов и регрессий производительности см. навык diagnose.
---

# 500 Internal Server Error Eliminator

Систематическая диагностика и устранение 500 ошибок в Django приложениях.

Связанное: для общего, не-Django-специфичного системного дебага (произвольные баги,
регрессии производительности, дисциплинированный цикл reproduce → minimise →
hypothesise → fix → regression-test) используй навык `diagnose`. Этот навык —
узкоспециализированный реактивный плейбук именно для Django 500.

## Quick Start: Diagnostic Workflow

При получении сообщения о 500 ошибке следуй этому порядку:

```
Task Progress:
- [ ] 1. Проверить логи ошибок
- [ ] 2. Определить точку возникновения (view/template/middleware)
- [ ] 3. Проверить недавние изменения (git diff)
- [ ] 4. Изолировать проблему
- [ ] 5. Применить исправление
- [ ] 6. Добавить превентивные меры
```

---

## Step 1: Проверка логов

Сначала найди, куда проект пишет логи. Типичные расположения (уточни структуру
конкретного проекта — пути ниже это примеры, а не жёсткие константы):

- `logs/errors.log`, `logs/django.log`, `logs/app.log`
- путь из `LOGGING` в settings (Grep по `LOGGING`, `FileHandler`, `filename`)
- системный журнал на production (journalctl, gunicorn/uwsgi error log, nginx error log)

Найди реальный лог-файл через Glob (`**/logs/*.log`, `**/*.log`) и прочитай его (Read).

```markdown
Ищи в логах:
1. Traceback     — полный stack trace ошибки
2. Timestamp     — когда произошла ошибка
3. Request path  — какой URL вызвал ошибку
4. Exception type — тип исключения (ImportError, AttributeError, etc.)
```

### Критические индикаторы в логах

| Паттерн в логе | Вероятная причина |
|----------------|-------------------|
| `ImportError: cannot import name` | Неправильный импорт, циклическая зависимость |
| `AttributeError: 'NoneType'` | Обращение к атрибуту None объекта |
| `TemplateSyntaxError` | Ошибка синтаксиса в шаблоне |
| `DoesNotExist` | Запрос несуществующего объекта БД без обработки |
| `KeyError` | Обращение к несуществующему ключу словаря |
| `Middleware` в traceback | Проблема в middleware цепочке |

---

## Step 2: Определение точки возникновения

### Анализ Traceback

Читай traceback **снизу вверх**:

1. **Последняя строка** — само исключение и его сообщение
2. **Предпоследняя рамка** — где именно произошла ошибка (файл + строка)
3. **Выше по стеку** — цепочка вызовов, которая привела к ошибке

### Категоризация по источнику

**View-level errors:**
```python
# Признаки: traceback указывает на views.py
# Частые причины:
# - Некорректная логика обработки данных
# - Отсутствие проверки на None
# - Неправильная работа с QuerySet
```

**Template-level errors:**
```python
# Признаки: TemplateSyntaxError или traceback в .html файле
# Частые причины:
# - Обращение к несуществующему атрибуту объекта
# - Неправильный синтаксис тегов {% %}
# - Использование фильтра с неправильным типом данных
```

**Configuration-level errors:**
```python
# Признаки: ошибка при запуске или в middleware
# Частые причины:
# - Опечатки в INSTALLED_APPS или MIDDLEWARE
# - Неправильные пути в TEMPLATES
# - Отсутствующие переменные окружения
```

---

## Step 3: Проверка недавних изменений

**Фокусируйся на:**
- Новые импорты (могут быть циклические или несуществующие)
- Изменения в views (новая логика, которая может упасть)
- Изменения в моделях (могут сломать существующие QuerySet)
- Изменения в шаблонах (новые теги/фильтры)
- Изменения в settings (могут сломать конфигурацию)

Команда: `git diff` / `git log --oneline -10` и просмотр последних правок затронутых файлов.

---

## Step 4: Изоляция проблемы

### Техника сужения области

1. **Определи scope:**
   - Ошибка на всех страницах? → Проблема в middleware/settings
   - Ошибка на одной странице? → Проблема в конкретном view/template
   - Ошибка после определенного действия? → Проблема в обработке данных

2. **Читай код целиком:**
   - Читай весь view function/class целиком
   - Проверяй все пути выполнения (if/else branches)
   - Ищи места, где может быть None без проверки

3. **Проверь связанные файлы:**
   - Если ошибка в view — читай используемый template
   - Если ошибка в template — читай view, который передает context
   - Если ошибка в model method — читай где этот метод вызывается

---

## Common Error Patterns и Workflow по типам

Каталог 5 типовых паттернов 500 (None, ImportError, TemplateSyntaxError, middleware,
KeyError) с примерами «было/стало» и пошаговые процедуры под View / Template /
Configuration ошибки вынесены в [references/error-patterns.md](references/error-patterns.md).
Открой нужный паттерн по типу исключения из traceback.

---

## Prevention Checklist

После исправления ошибки, добавь превентивные меры:

### Для View ошибок:
- [ ] Добавлены проверки на None для всех QuerySet операций
- [ ] Добавлен try/except для опасных операций
- [ ] Добавлена валидация входных данных
- [ ] Рассмотрена возможность unit теста для edge case

### Для Template ошибок:
- [ ] Добавлены {% if %} проверки перед обращением к атрибутам
- [ ] Все необходимые {% load %} теги на месте
- [ ] Проверены все вложенные блоки на закрытие

### Для Configuration ошибок:
- [ ] Проверены все пути на существование
- [ ] Проверены импорты на корректность
- [ ] Добавлены комментарии для неочевидных настроек

---

## Контекст окружения: где запускать, а где нет

Часто диагностика идёт на локальной машине (нередко Windows), а ошибка
воспроизводится на production (Linux-сервер). В таком случае:

НЕ пытайся локально запускать (если нет настроенной БД/окружения):
- `python manage.py check` (требует БД)
- `python manage.py runserver`
- Любые Django management команды, требующие подключения к БД/сервисам

Можно делать всегда:
- Читать файлы напрямую (Read)
- Проверять Python синтаксис статически
- Анализировать код (Grep/Glob)
- Читать логи (найденный лог-файл проекта)

Если же окружение настроено и БД доступна — запуск management-команд и
воспроизведение ошибки локально приветствуется (см. навык `diagnose`, шаг reproduce).

---

## Quick Reference Card

При 500 ошибке задай себе эти вопросы:

1. **Что показывает traceback?** → Найди и прочитай лог-файл проекта
2. **Где произошло?** → View / Template / Config
3. **Что изменилось?** → Читай git diff
4. **Есть ли None?** → Проверь все QuerySet и dict операции
5. **Есть ли импорты?** → Проверь циклические зависимости
6. **Правильный ли template синтаксис?** → Проверь теги и фильтры
7. **Что в context?** → Проверь view передает нужные данные