그룹 교육과정에 *레벨 25* 를 지정해 둔 회원이 *배치고사 건너뛰기* 직후 *레벨 15* 로 배정된 사고. 표면 증상은 하나였지만 진짜 원인은 *Class 동기화 누락 / getEffectiveCurriculum 폴백 누락 / 배치고사 건너뛰기의 currentLevelId 폴백* 세 도메인 버그가 한 사슬을 이루고 있던 점이었다. 폴백 4 단으로 재정렬하고 자동 승급 메서드 두 개를 들여 *EXCELLENT 3 일 + Top 도달* 조건을 한 흐름에 묶은 A 톤 트러블슈팅을 정리한다.
한 고객사에서 연락처 010-1234-5678 을 입력하면 BE 400, 01012345678 을 입력하면 통과되는 비대칭이 보고됐다. DB 를 열어 보니 같은 컬럼에 *하이픈 포함* 과 *숫자만* 이 섞여 누적돼 있었다. 진짜 범인은 *저장 포맷·입력 포맷·표시 포맷 세 축의 표준이 어디에도 없었던 점* 이었다. BE `phone.util.ts` + DTO `@Transform/@Matches` + FE zod `transform/refine` + 마이그레이션 SQL 을 *한 머지에 묶어* BE·FE·DB 세 곳을 동시에 정규화한 트러블슈팅을 정리한다.
Unity 주간 출석 API 가 운영 한 달 후 월요일 칸만 무작위로 비었다. DB 에는 COMPLETED 과제가 분명히 있는데 화면은 null 이었다. 진짜 범인은 `new Date('2026-03-09')` 가 ISO 8601 로 파싱되어 UTC 자정 (= KST 09:00 월) 으로 잡힌 점이었고, batch 가 KST 00:00 으로 고정한 scheduledAt 이 쿼리 범위 *직전 9 시간* 에 들어가 통째로 누락되고 있었다. KST 자정 명시 생성자로 두 줄을 갈아끼우고, ESLint 룰과 jest mocking 가드로 재발을 막은 트러블슈팅을 정리한다.
외부 뷰어 리포트 4탭 N+1 을 잡아 2.3 초까지 줄였는데 목표 500ms 와의 마지막 1.8 초가 코드 어디에서도 나오지 않았다. Cloud SQL Query Insights 가 쿼리 자체는 0.1~1ms 라고 답했다. 진짜 범인은 한국 ↔ us-central1 왕복 100~200ms × 응답당 6~8 쿼리 누적이었다. 레플리카 프로모션으로 asia-east1 (대만) 으로 옮기고 .env 두 줄을 갈아끼우자 `/content-candidates` 가 2,340ms → 682ms (71% ↓), `/student/home` 이 2,000ms+ → 400~600ms 로 떨어졌다. 인덱스·N+1 이 아니라 리전·RTT 가 본진이었던 인프라 사고를 정리한다.
외부 뷰어 리포트 토큰 한 줄로 들어가는 공개 페이지의 4탭 단일 응답이 최대 14.4초까지 늘어났다. Prisma `include` 만 의심하다 진짜 범인을 놓쳤다. 두 층의 N+1 — 4탭 빌더 6 건의 순차 await + 일별·주별 for 루프 안 `findMany` 반복 — 을 Promise.all 병렬화 + 단일 findMany + 메모리 그룹핑으로 풀어 55 개 쿼리를 10 개로, p95 응답을 ~2.3 초로 끌어내린 트러블슈팅을 정리한다.
외부 뷰어 리포트의 4탭에 인사이트 카드와 빈 데이터 폴백을 같이 깔고 나니 일부 motion.section의 whileInView 애니메이션이 트리거되지 않았다. 같은 컴포넌트가 같은 코드로 어떤 탭에서는 정상이고 어떤 탭에서는 opacity 0으로 그대로 멈췄다. 원인은 조건부 마운트 시점에 IntersectionObserver의 첫 콜백이 framer-motion 이펙트 부착 전에 끝나 버린 레이스 + viewport.once 기본값 false의 합이었다. once:true 표준화 + sentinel ref + ESLint 가드를 같이 깐 트러블슈팅을 정리한다.
운영자가 본인 담당 클래스 1개만 떠야 하는데 모든 클래스가 떴다. 목록 API에 operatorId 필터를 깔고 끝낸 줄 알았는데, 직접 URL로 미담당 클래스 ID를 두드리니 상세·수정·승인 5개 엔드포인트가 그대로 200을 돌려줬다. 원인은 JWT payload.sub(User ID)와 Operator 테이블 id(Operator ID)의 분리 + validateClassAccess 헬퍼 부재 둘이었다. 라운드 한 번에 BE → QA → 추가 BE → QA 재검증으로 닫은 NestJS ForbiddenException + Prisma classOperator.findFirst 패턴을 정리한다.
QA Round 2에서 EC-3 엣지 케이스가 잡은 타이머 NaN:NaN 버그. 같은 컴포넌트가 같은 코드로 한 화면에서 정상, 다른 화면에서 NaN:NaN으로 뜨던 패턴이다. 원인은 BE 응답 DTO에서 한 필드 누락 + FE 무방어 + seed 데이터 부족 세 가지의 합이었다. 응답 스키마 검증과 콘텐츠 후보 0건 방어를 같이 깐 라운드 회고.
첫 배치 작업으로 짠 NestJS 킥오프 배치(@nestjs/schedule)가 @Cron('EVERY_HOUR') + findExpiredAssignments() 시간 체크 누락 두 함정에 걸려 모든 ACTIVE 숙제를 매시간 EXPIRED로 굳혀 버린 사고를 복기한다. fix는 두 줄(시간 비교 + cron 표현식)이었지만, 사고가 일어났는데도 콘솔이 흘러가 흔적이 없었던 점이 더 컸다. 콘솔 일변도에서 Winston 파일 로깅(daily-rotate, app/error 분리, GCP severity) 으로 갈아탄 결정과 설정 전문을 정리한다.
Unity WebView 호스트가 보낸 첫 contentInit 메시지를 웹 콘텐츠가 0개로 인식하는데 에러는 없다. window.vuplex가 비동기로 주입되는 탓에 detectMode()가 'standalone'을 오판하고, isStandalone() 가드가 메시지 핸들러 등록을 막은 침묵 실패를 추적해 해결한 기록.
활동 로그 인터셉터에서 request.user가 undefined로 잡혔다. 원인을 파고드니 JwtAuthGuard 구현 누락, Auth Service와 Guard 간 JWT_SECRET 불일치, FE의 base64(JSON) Mock 토큰까지 3중 함정이 차례로 드러났다. 새벽 3시 임시 우회부터 다음 날 17시 정상화까지의 디버깅 흐름과 NestJS 글로벌 Guard·명시적 secret 검증·실제 BE API 시드 패턴을 정리한다.
초기 배치고사는 정확도로 회원 레벨을 자동 배치하려 했지만, 출제 문제 셋이 바뀌면 레벨이 출렁였다. 측정과 결정을 분리해 레벨 배치 로직을 걷어내고 5지표 정확도 측정만 남긴 명세 갱신과 트레이드오프 4건을 정리한다.
단일 정수 sortOrder로 줄세운 선형 레벨을 노드/엣지 분리 DAG로 옮겼다. 셀프 참조 1:N vs 별도 엣지 테이블, PostgreSQL recursive CTE로 진행도 계산, 엣지 INSERT 시점 사이클 검출, 선형 i→i+1 자동 마이그레이션 4가지 결정과 zod invariants e2e로 회귀를 차단한 트러블슈팅.
Prisma seed 스크립트에서 deleteMany 순서를 잘못 잡으면 FK 제약 조건 위반으로 터진다. 30개 테이블의 의존 그래프를 분석하고 자식→부모 역순 삭제 패턴을 정립한 실전 삽질기.
Claude Max 플랜의 OAuth 토큰(sk-ant-oat)으로 Messages API를 직접 호출하면 429 Rate Limit이 뜹니다. Claude Code의 인증 우선순위 5단계, sk-ant-oat vs sk-ant-api 차이, 그리고 스크립트에서 Max 플랜을 활용하는 우회법을 실제 트러블슈팅 사례와 함께 정리합니다.
Vite 프로젝트에서 새 패키지를 설치한 뒤 Invalid hook call 에러가 발생하는 원인은 의존성 사전 번들링 캐시(.vite/deps)다. React 중복 인스턴스 문제의 근본 원인부터 node_modules/.vite 삭제, vite --force, optimizeDeps 설정까지 실전 해결법과 예방 전략을 정리한다.
NestJS + Prisma 프로젝트에서 schema.prisma에 새 필드를 추가한 뒤 prisma generate를 빠뜨리면, TypeScript 빌드는 as any 캐스팅 덕에 통과하지만 런타임에서 Prisma Client가 새 필드를 모른다. pnpm build와 prisma generate가 별개 명령인 구조적 함정, prebuild 훅으로 자동화하는 해결법, Docker와 CI에서 놓치지 않는 예방 전략을 실전 코드와 함께 정리한다.
Refine의 useCustom hook에서 config.query 객체에 number 타입 값을 전달해도, URL 쿼리 파라미터로 직렬화되면서 문자열이 된다. NestJS @Type(() => Number) 검증과 조합하면 targetClassId must be an integer number 400 에러가 터진다. URL 직접 삽입 패턴으로 해결한 실전 사례를 정리한다.
NestJS + Prisma 프로젝트에서 Soft Delete 필터를 Application Service에만 적용하고 Domain Repository를 누락하면, 삭제된 데이터가 배치 프로세스와 조회 API에서 좀비처럼 되살아난다. PM 코드 리뷰에서 11곳 추가 발견된 실전 사례를 통해, 레이어별 필터 점검 체크리스트와 grep 기반 검증법을 정리한다.
react-hook-form과 Zod를 연동할 때 자주 발생하는 6가지 트러블슈팅 사례를 정리합니다. zodResolver 미연결, defaultValues 타입 불일치, mode 설정 누락 등 실전에서 놓치기 쉬운 함정과 해결법을 코드와 함께 설명합니다.
NestJS 서비스에서 메서드 간 재귀 호출이 발생하면 스택 오버플로우와 504 Gateway Timeout이 터진다. 통계 API에서 추세 계산이 무한루프에 빠진 실전 사례를 통해, 재귀 호출 탐지법과 skipFlag 패턴으로 방어하는 방법을 정리한다.
Framer Motion whileInView로 만든 스크롤 애니메이션이 Chrome DevTools MCP 스크린샷이나 OG 이미지 생성에서 보이지 않는 원인은 IntersectionObserver의 뷰포트 의존성이다. initial hidden 상태가 캡처되는 근본 원인과 3가지 해결 전략을 실전 코드로 정리한다.
Docker에서 pnpm 모노레포 NestJS 프로젝트를 빌드하면 TypeScript 데코레이터 에러가 3132개 터진다. TypeScript 버전 충돌부터 tsconfig 누락, pnpm deploy --legacy, Prisma Client 수동 복사까지 — 4가지 함정과 해결법을 실전 코드로 정리한다.
NestJS에서 Nest can't resolve dependencies 에러를 만나면 당황스럽습니다. 모듈 imports 누락, @Injectable() 빠짐, 순환 참조까지 — DI 에러의 3대 원인을 실전 코드로 분석하고, 서버 기동 테스트로 사전에 잡는 방법을 정리합니다.
shadcn init 실행 후 커스텀 CSS 변수가 기본값으로 덮어씌워지는 문제의 원인과 해결법을 정리합니다. 디자인 토큰이 초기화되는 근본 원인을 분석하고, git diff 기반 복구 및 예방 패턴을 코드와 함께 설명합니다.
Prisma seed 스크립트에서 deleteMany 순서를 잘못 잡으면 FK 제약 조건 위반 에러가 발생합니다. 테이블 의존 관계를 분석하고 자식→부모 순으로 삭제하는 실전 패턴을 정리합니다. 바로 적용할 수 있는 방법을 알려드릴게요.
Prisma가 생성한 enum과 도메인 타입이 TypeScript에서 호환되지 않아 빌드 에러가 발생합니다. 명시적 캐스팅 패턴과 아키텍처별 예방 전략을 정리합니다.
API가 200 OK를 반환하는데 프론트엔드에서 에러 페이지가 뜬다면, BE 응답 래퍼 구조를 의심하세요. useCustom + ApiWrapper 패턴으로 2중 언래핑하는 실전 해결법을 정리합니다.
React useEffect의 비동기 cleanup이 Pixi.js RenderTexture를 파괴하는 레이스 컨디션 버그를 추적합니다. 웹 브라우저에서는 정상인데 Vuplex WebView + 고사양 GPU에서만 재현되는 3중 함정의 원인과 해결법을 정리합니다.
NestJS + Prisma에서 콘텐츠 등록 시 Foreign key constraint violated 500 에러가 터졌습니다. 존재하지 않는 Level ID가 원인이었고, 저장 전 검증 패턴으로 해결한 과정을 정리합니다.
NestJS에서 DTO를 interface로 만들면 400 에러와 Swagger 스키마 누락이 동시에 발생합니다. class-validator와 @ApiProperty가 작동하는 원리부터 해결까지 정리했습니다.
Refine 기반 React 어드민에서 DataProvider 커스터마이징 시 흔히 겪는 두 가지 함정을 정리합니다. BE가 객체를 반환하는데 useList를 쓴 경우, 그리고 total 파싱 경로가 어긋난 경우의 증상·원인·해결법입니다.
NestJS + Prisma 마이그레이션에서 테이블 하나를 빠뜨려 운영 DB에 컬럼 없음 에러가 터졌습니다. schema.prisma 변경 시 모든 모델을 확인하는 체크리스트와 migrate diff 예방법을 정리했어요.
Vite 6.x 개발 서버 프록시 환경에서 PATCH 요청만 CORS 에러가 발생하는 원인은 HTTP 메서드 대소문자입니다. toUpperCase() 한 줄로 해결하는 방법과 프록시 디버깅 체크리스트를 정리합니다.
PATCH 요청만 CORS에 막힌다면 allowedHeaders와 Vite 프록시를 의심하세요. 프리플라이트부터 해결까지 실전 트러블슈팅 기록. 지금 바로 확인해 보세요.