Django를 처음 시작하거나 어느 정도 개발을 진행하고 있어도 반복적으로 마주하게 되는 오류들이 있습니다. 대부분은 기본 설정에서 사소한 부분을 놓쳐 발생하는 경우가 많습니다. 이번 글에서는 장고 프로젝트에서 자주 발생하는 대표적인 오류 5가지를 정리하고, 오류 원인과 해결 방법까지 함께 안내합니다.
장고 개발을 하며 다음 문제를 한 번이라도 겪어본 적 있다면 참고해 보세요.
1. INSTALLED_APPS에 앱 등록 누락
장고 앱을 생성한 뒤 INSTALLED_APPS에 추가하지 않으면 다음 문제가 발생합니다.
- 모델이 데이터베이스에 마이그레이션되지 않음
- 템플릿 및 정적 파일 로딩 문제 발생
- 에러 메시지가 간접적이라 초보자들이 특히 많이 놓치기 쉬움
해결 방법
settings.py의 INSTALLED_APPS에 앱 이름을 반드시 추가합니다.
INSTALLED_APPS = [
...
'myapp',
]
2. 마이그레이션 충돌 및 불일치
장고 프로젝트에서 가장 자주 보게 되는 에러 중 하나입니다.
- 모델 수정 후
makemigrations를 안 한 경우 - 여러 브랜치에서 모델 구조가 달라 충돌이 생긴 경우
대표적으로 다음 오류가 표시됩니다.
- You have unapplied migrations
- Conflicting migrations detected
해결 방법
마이그레이션 상태를 먼저 확인한 뒤 정리합니다.
python manage.py makemigrations
python manage.py migrate
충돌이 생기면 충돌된 파일 비교 후 하나로 합쳐야 합니다.
3. URL 패턴 충돌 또는 누락
urls.py 설정 오류로 인해 다음 문제가 자주 발생합니다.
- include 경로 오타 또는 누락
- 중복된 URL 패턴
- 슬래시(/) 유무 처리 미흡
대표 에러:
- 404 Not Found
- NoReverseMatch
- Reverse for … not found
해결 방법
URL 네임스페이스를 정확히 사용하고, URL 패턴을 구조적으로 관리합니다.
예시:
from django.urls import path, include
urlpatterns = [
path('blog/', include('blog.urls')),
]
4. 템플릿 경로 및 변수 오류
템플릿 로딩 관련 문제는 다음과 같습니다.
- 템플릿 파일 위치가 잘못됨
{% url %}또는{{ variable }}변수명 오타- 앱 단위 템플릿 구조를 잘못 적용함
대표 오류:
- TemplateDoesNotExist
- VariableDoesNotExist
권장 템플릿 구조 (앱 기준)
myapp/
templates/
myapp/
index.html
템플릿 내 변수명은 반드시 views에서 넘긴 이름과 동일해야 합니다.
5. STATIC/MEDIA 설정 오류
개발 서버에서는 정상 동작하지만 배포 환경(Nginx, Apache)에서 문제가 발생하는 대표 원인입니다.
문제 원인:
- STATIC_ROOT, MEDIA_ROOT 설정 누락
collectstatic실행하지 않음- 서버 정적 파일 경로 미설정
결과:
- CSS, JS, 이미지 로딩 실패
해결 설정 예시
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'
배포 환경에서:
python manage.py collectstatic
마무리: 장고 개발 시 체크리스트 활용하기
장고는 강력한 프레임워크지만 설정 의존도가 높기 때문에 작은 실수가 큰 오류로 이어집니다. 위 문제들은 대부분 설정 파일 점검, 마이그레이션 관리, 폴더 구조 검증만으로 해결할 수 있습니다.
앞으로 장고 프로젝트를 진행할 때 아래 체크리스트를 기억해 두세요.
- 앱 생성 후 INSTALLED_APPS 등록했는가?
- 모델 수정 시 마이그레이션 반영했는가?
- URL 패턴에 중복 또는 오타가 없는가?
- 템플릿 폴더 구조와 변수명이 정확한가?
- STATIC/MEDIA 설정이 배포 환경에서도 유효한가?
이 글이 장고 오류 해결에 도움이 되길 바랍니다.
다음에는 배포 시 자주 발생하는 서버 설정 문제도 함께 다뤄보겠습니다.