[트러블슈팅] Airflow에서 pipeline 패키지 인식하지 못했던 이유와 해결 과정

Airflow DAG에서

from pipeline.orders.extract import extract_raw

와 같은 import를 사용했지만, DAG Import Error가 발생하며 pipeline을 찾지 못하는 문제가 발생했다.

 

처음에는 Python 경로(PYTHONPATH) 문제로 판단하여 Airflow 컨테이너 Web UI 기준으로 sys.path를 확인했다.
하지만 Webserver 컨테이너 기준 경로(/usr/local/lib/...)만 확인될 뿐, 우리가 기대한 /opt/airflow/pipeline은 존재하지 않았다.

 

 

그래서 Webserver뿐 아니라 Scheduler / Worker 컨테이너로 직접 진입해 확인해보니,
문제의 핵심은 경로 설정 이전에 pipeline 폴더 자체가 컨테이너에 없다는 점이었다.

 

원인은 docker-compose.yaml의 volume 설정이었다.
기본 설정에서는 dags, logs, plugins만 마운트되고 있었고,
pipeline 폴더는 컨테이너로 전달되지 않고 있었다.

 

 

해결은 두 단계로 진행했다.

 

첫째, pipeline 폴더를 컨테이너에 마운트했다.

volumes:
  - ./pipeline:/opt/airflow/pipeline

둘째, Python이 해당 경로를 모듈 탐색 대상으로 인식하도록 PYTHONPATH를 설정했다.
이 설정은 모든 Airflow 컴포넌트에 적용되도록 공통 환경 설정에 추가했다.

이후 컨테이너를 재시작하자 Webserver와 Scheduler 모두에서
pipeline 모듈을 정상적으로 import할 수 있었고, DAG Import Error도 해결되었다.

 

이번 문제를 통해
**“Airflow에서 import 에러가 나면 코드보다 먼저 컨테이너의 실제 파일 존재 여부와 PYTHONPATH를 확인해야 한다”**는 점을 명확히 정리할 수 있었다.

 

Airflow에서 pipeline을 못 찾았던 이유는 경로 문제가 아니라 컨테이너에 마운트되지 않았기 때문이었고,

volume 마운트 + PYTHONPATH 설정을 함께 적용해 해결했다.