Troubleshooting

이 랩을 진행하며 학습자가 마주치는 실패에 대한 증상, 원인, 해결 방법 레퍼런스로, 문제가 드러나는 지점별로 묶여 있다.

아래의 모든 항목은 실제로 일어난 실패다. 랩의 각 파트 README에 문서화된 열한 개와, 이 워크샵을 만들고 테스트하는 동안 발견한 다섯 개다. 자신의 증상을 찾아 원인을 읽고 해결 방법을 적용하라. 여기에 맞는 것이 없다면, Instructor 트랙의 ## Common failures 섹션이 각 모듈의 진행자 관점을 더 깊이 다루며, 그다음 단계는 담당 솔루션 아키텍트다.

툴체인과 환경 설정

`dbt`가 `mashumaro` import 오류로 실패하거나 설치되지 않는다

증상 - dbt-snowflake 또는 dbt-clickhouse 설치가 실패하거나, dbt가 Python 버전과는 겉보기에 아무 관계 없어 보이는 mashumaro 관련 import 오류를 낸다.
원인 - dbt-snowflake와 dbt-clickhouse는 모두 Python 3.11, 3.12, 또는 3.13을 요구한다. Python 3.14+는 두 어댑터가 공유하는 mashumaro 의존성을 깨뜨리며, 실패는 보통 실수가 이미 저질러진 뒤 무관한 모듈에서 드러난다.
해결 - 시스템 Python과 함께 3.13을 설치하고(예: brew install python@3.13) 그 인터프리터를 명시해 virtualenv를 다시 만든다: python3.13 -m venv .venv.

Snowflake 소스 환경

`terraform init`이 프로바이더 오류로 실패한다

증상 - workshop_public/snowflake_migration_lab/01-setup-snowflake/에서 terraform init이 프로바이더를 해석하는 중에 실패한다.
원인 - Terraform 바이너리가 오래되었거나 Terraform 레지스트리에 대한 네트워크 접근이 없다.
해결 - Terraform >= 1.6을 사용하고 레지스트리에 대한 인터넷 접근을 확인한다.

`snowsql` 연결이 거부된다

증상 - snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER}가 연결을 거부한다.
원인 - SNOWFLAKE_ORG 또는 SNOWFLAKE_ACCOUNT가 잘못되었다.
해결 - 만든 계정과 두 값을 다시 대조한 다음, 같은 snowsql 명령을 재시도한다.

`dbt run`이 `relation not found`로 실패한다

증상 - Part 1 dbt 프로젝트에서 dbt run이 존재하지 않는 릴레이션을 보고한다.
원인 - 데이터베이스 구조가 만들어진 적이 없다.
해결 - 먼저 ./setup.sh --skip-seed를 실행하고, profiles.yml이 NYC_TAXI_DB를 가리키는지 확인한다.

Superset이 `connection refused`를 표시한다

증상 - docker-compose up 직후 Part 1 Superset UI가 연결을 거부한다.
원인 - Superset이 초기화되는 데 약 60초가 걸린다.
해결 - 60초 기다린 뒤 재시도한다. 그래도 실패하면 docker logs nyc_taxi_superset을 확인한다.

데이터 시딩이 예상보다 오래 걸린다

증상 - workshop_public/snowflake_migration_lab/01-setup-snowflake/의 시딩 단계가 멈춘 것처럼 보인다.
원인 - 이 규모에서는 정상적인 Snowflake 동작이며, 멈춘 것이 아니다. 5천만 행을 만드는 TABLE(GENERATOR) 삽입은 약 10-12분이 걸리고, 5천만 행 전체에 VARIANT TRIP_METADATA 컬럼을 채우는 후속 UPDATE는 SMALL 웨어하우스에서 추가로 15-20분이 걸린다.
해결 - 그냥 두어라. 두 단계 모두 대화형이 아니며, 재시도할 것이 없다.

ClickHouse Cloud 프로비저닝과 데이터 마이그레이션

Terraform 인증이 401 Unauthorized로 실패한다

증상 - workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/의 Terraform apply가 401 Unauthorized로 실패한다.
원인 - CLICKHOUSE_TOKEN_KEY 또는 CLICKHOUSE_TOKEN_SECRET이 잘못되었거나, 키에 필요한 스코프가 없다.
해결 - ClickHouse Cloud UI의 Settings -> API keys에서 키 페어를 다시 생성하고, Admin 스코프가 있는지 확인한다.

마이그레이션 스크립트가 실행 중에 실패한다

증상 - scripts/02_migrate_trips.py가 5천만 행 복사 중간에 죽는다.
원인 - 장시간 전송 중의 일시적인 네트워크 또는 웨어하우스 문제.
해결 - --resume으로 다시 실행한다. 스크립트는 ClickHouse에 이미 있는 max(pickup_at)에 워터마크를 잡고 이미 적재한 행은 건너뛴다.
```
python scripts/02_migrate_trips.py --resume
```

마이그레이션 스크립트 연결 오류

증상 - 마이그레이션 스크립트가 Snowflake나 ClickHouse에 접근할 수 없다.
원인 - 현재 셸에서 Snowflake 또는 ClickHouse 환경 변수 하나 이상이 설정되지 않았다.
해결 - 값을 확인한 다음, 재시도 전에 상태 파일을 다시 source 한다.
```
echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD
```
먼저 source .env && source .clickhouse_state를 실행하고 재시도한다.

`dbt run`이 `Connection refused` 또는 `Unknown host`로 실패한다

증상 - ClickHouse 프로젝트에 대한 dbt run이 호스트를 해석하거나 연결하지 못한다.
원인 - 현재 셸에 CLICKHOUSE_HOST가 설정되지 않았다.
해결 - 모듈 디렉터리에서 source .clickhouse_state를 실행한 다음 dbt run을 재시도한다.

`dbt`가 `Could not find profile named 'nyc_taxi_ch'`로 실패한다

증상 - workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch에서 dbt debug 또는 dbt run이 프로파일 없음 오류로 즉시 실패한다.
원인 - ClickHouse dbt 프로파일이 ~/.dbt/profiles.yml에 추가된 적이 없다.
해결 - workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example을 열어 그 안의 nyc_taxi_ch: 블록을 기존 ~/.dbt/profiles.yml에 두 번째 최상위 프로파일로 병합한다. 파일을 덮어쓰지 마라 - 그렇게 하면 모듈 01의 nyc_taxi: 프로파일이 삭제되고 그 모듈의 4단계 갱신 루프가 깨진다. 이 병합 단계를 전부 다루는 03 프로비저닝과 마이그레이션을 참고하라.

ClickHouse에서의 dbt

dbt 실행 후 `analytics.agg_hourly_zone_trips`가 비어 있다

증상 - 모듈 04의 dbt run 후 analytics.agg_hourly_zone_trips의 행이 0이고, 이를 사용하는 대시보드 차트에 데이터가 표시되지 않는다.
원인 - 실패가 아니라 예상된 결과다. 이 모델의 증분 필터는 WHERE pickup_at >= now() - INTERVAL 2 HOUR이며, 라이브 트립 프로듀서가 쓴 행만 매칭한다. 마이그레이션 스크립트가 옮긴 모든 행은 과거 데이터이므로 그 2시간 윈도우 안에 들어오는 것이 없다.
해결 - 고칠 것이 없다. 여기서는 0이 올바른 값이다. 이 테이블은 05 벤치마크와 컷오버의 컷오버 단계 이후 프로듀서가 ClickHouse에 직접 쓰기 시작하면 채워진다.

대시보드와 벤치마크

Superset이 403 Forbidden을 표시한다

증상 - 모듈 중간에 Superset UI가 403 Forbidden을 반환한다.
원인 - 세션 쿠키가 만료되었다.
해결 - 로그아웃하고 http://localhost:8088에서 다시 로그인한 다음 bash superset/add_clickhouse_connection.sh를 다시 실행한다.

벤치마크가 Q7에 `N/A`를 표시한다

증상 - run_benchmark.sh의 출력 CSV에서 쿼리 7의 속도 향상 값 자리에 N/A가 있다.
원인 - 벤치마크 스크립트가 ClickHouse에 연결할 수 없었다.
해결 - CLICKHOUSE_HOST가 설정되어 있고(source .clickhouse_state) 서비스가 실행 중인지 확인한 다음 벤치마크를 다시 실행한다.

임포트한 Superset 대시보드가 ClickHouse에 연결되지 않는다

증상 - Superset에 임포트한 대시보드는 열리지만 차트가 ClickHouse에 접근하지 못한다.
원인 - 커밋된 익스포트 ZIP은 호스트가 your-instance.clickhouse.cloud로 가려져 있다. add_clickhouse_connection.sh는 임포트 전에 .env에서 실제 URI를 패치해 넣지만, Superset UI를 통한 수동 임포트는 그렇지 않다.
해결 - 수동 임포트 대신 bash superset/add_clickhouse_connection.sh를 사용하거나, 이후 연결을 편집해 실제 CLICKHOUSE_HOST와 자격 증명을 사용하게 한다.

컷오버와 패리티

패리티 확인이 실패하거나, 컷오버에서 행이 사라진 것처럼 보인다

증상 - 모듈 05의 행 수 패리티 확인이 실패하거나, 컷오버가 데이터를 잃은 것처럼 보인다.
원인 - --resume 따라잡기 패스를 건너뛰었다. Snowflake 프로듀서는 모듈 01-05 내내 계속 쓰므로, 모듈 03의 마이그레이션은 데이터의 앞부분만 포착했다. 꼬리 부분은 따라잡기 전까지 Snowflake에만 존재한다. Snowflake 프로듀서를 일찍 멈추면(예: 모듈 01 직후) 따라잡을 꼬리가 남지 않으므로 이 모듈의 컷오버 시연이 조용히 망가진다.
해결 - 패리티를 확인하기 전에 따라잡기 패스를 실행한다. 공백 행만 옮기므로 원래의 40-50분이 아니라 수 초에서 수 분이 걸린다.
```
python scripts/02_migrate_trips.py --resume
bash scripts/01_verify_migration.sh
```