레퍼런스

트러블슈팅 모음 — 실제 오류 15가지

배포 과정에서 실제로 마주치는 오류와 검증된 해결책

범례: BE 백엔드/Lambda FE 프론트엔드/Next.js IAM 권한 CF CloudFront/S3 AZ Azure AD

ImportError cryptography No space left Function already exists 500 캐싱 SSL 오류 CORS preflight CORS 실제 요청 AADSTS50011 interaction_in_progress 5-part JWT audience 실패 window is not defined React 19 빌드 CloudFront 304 AccessDeniedException

Lambda에서 cryptography ImportError

Runtime.ImportModuleError: No module named 'cryptography'

원인

Mac에서 pip install한 cryptography는 Mac용 바이너리입니다. Lambda는 Linux 환경 — 다른 바이너리가 필요합니다.

해결

zappa_settings.json에 "use_precompiled_packages": true와 "manylinux": true 추가 후 zappa update

# zappa_settings.json
"use_precompiled_packages": true,
"manylinux": true

Lambda /tmp 디스크 가득 참

OSError: [Errno 28] No space left on device

원인

기본 Lambda /tmp 512MB. Zappa 패키지 압축 해제 시 초과 가능. ephemeral_storage 설정이 Lambda에 반영 안 된 경우.

해결

Lambda 콘솔 → 함수 → 구성 → 일반 구성 → 임시 스토리지를 1024 MB로 수동 변경

zappa deploy 시 "Function already exists"

botocore.exceptions.ClientError: Function already exists: gsr-my-project

원인

Lambda 함수가 이미 존재하는데 zappa deploy(신규 생성 전용)를 실행했습니다.

해결

재배포 시에는 항상 zappa update prod를 사용하세요.

API Gateway가 500 에러를 계속 반환 (캐싱)

HTTP 500 — 코드 수정 후에도 동일한 500이 반복됨

원인

API Gateway EDGE 타입은 500 오류를 최대 5분 캐싱합니다. 코드를 고쳐도 캐시 만료까지 500이 계속 나옵니다.

해결

zappa_settings.json에 "api_gateway_endpoint_type": "REGIONAL" 추가 후 재배포. REGIONAL은 500 캐싱이 없습니다.

SSL 인증서 검증 실패 (사내망)

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

원인

GS Retail 사내망에서 Azure AD JWKS 조회 시 회사 CA 인증서를 Python이 신뢰하지 않음.

해결

pip install truststore 후 app.py에 조건부 import 패턴 추가. 시스템 인증서 저장소의 회사 CA를 Python이 신뢰하게 됩니다.

CORS preflight(OPTIONS) 실패

Access to fetch blocked by CORS policy: Response to preflight has invalid HTTP status code 403

원인

브라우저의 OPTIONS preflight가 API Gateway에서 거절됨. Flask-CORS만 설정하고 API Gateway CORS를 설정하지 않은 경우.

해결

zappa_settings.json에 "cors": true 추가 후 zappa update. API Gateway 레벨에서 OPTIONS를 자동 처리합니다.

CORS 실제 요청(POST) 실패

Access to fetch blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present

원인

OPTIONS는 통과하지만 POST 응답에 CORS 헤더가 없음. Flask-CORS 미설정 또는 origins에 현재 도메인이 없는 경우.

해결

app.py에 Flask-CORS 설정 추가. origins에 CloudFront URL과 localhost 모두 포함.

CORS(app, resources={r"/api/*": {
    "origins": ["https://xxxx.cloudfront.net", "http://localhost:3000"],
    "methods": ["GET", "POST", "OPTIONS"],
    "allow_headers": ["Authorization", "Content-Type"],
}})

AADSTS50011 — 리다이렉트 URI 불일치

AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application

원인

MSAL의 redirectUri 값이 Azure Portal에 등록된 URI와 일치하지 않습니다. CloudFront URL 변경 후 업데이트를 안 한 경우도 이 오류입니다.

해결

Azure Portal → 앱 등록 → 인증 → 리다이렉트 URI에 현재 URL을 등록합니다. localhost와 CloudFront URL 모두 필요합니다.

interaction_in_progress — MSAL 상태 충돌

BrowserAuthError: interaction_in_progress: Interaction is currently in progress

원인

MSAL 리다이렉트 도중 탭을 닫거나 새로고침하면 sessionStorage에 stale 인터랙션 상태가 남습니다.

해결

sessionStorage에서 interaction.status를 포함하는 키를 모두 제거합니다.

// 브라우저 콘솔에서 실행
Object.keys(sessionStorage)
  .filter(k => k.includes('interaction.status'))
  .forEach(k => sessionStorage.removeItem(k))

// 또는 전체 세션 초기화
sessionStorage.clear()

5-part JWT 파싱 오류

jwt.exceptions.DecodeError: Not enough segments (expected 3, got 5)

원인

Azure AD가 가끔 access_token + id_token을 이어붙인 5-part JWT를 발급합니다. PyJWT는 이 형식을 모릅니다.

해결

token_manager.py의 _sanitize_token() 메서드가 처리합니다. 이 메서드가 없으면 추가해야 합니다. Module 01 참조.

JWT audience 검증 실패

jwt.exceptions.InvalidAudienceError: Invalid audience

원인

토큰의 aud claim이 api://CLIENT_ID 형식이 아닌 경우. Azure Portal에서 앱 등록 → 애플리케이션 ID URI가 설정되지 않은 경우.

해결

Azure Portal → 앱 등록 → API 표시 → 애플리케이션 ID URI를 api://CLIENT_ID로 설정합니다. AuthManager의 self.audience 값과 일치해야 합니다.

window is not defined — MSAL SSR 오류

ReferenceError: window is not defined (during pnpm build)

원인

MSAL이 pre-render(서버사이드) 단계에서 실행됩니다. window는 브라우저에만 있는 객체입니다.

해결

SSR 격리 3파일 패턴을 적용합니다. AuthProvider.tsx → ClientOnlyAuth.tsx를 next/dynamic으로 ssr: false로 로드. Module 03 참조.

React 19 빌드 실패

Error: useLayoutEffect does not work on the server. Consider using useEffect instead. (fatal in output: 'export' mode)

원인

React 19에서 output: 'export'와 함께 사용 시 pre-render 단계의 경고가 빌드 오류로 격상됩니다.

해결

package.json에서 React를 18.3.1로 고정합니다. pnpm은 overrides 섹션 사용.

# package.json
"pnpm": {
  "overrides": {
    "react": "18.3.1",
    "react-dom": "18.3.1"
  }
}

CloudFront에서 이전 버전 HTML 계속 서빙

S3 업로드 후에도 CloudFront에서 구버전 HTML이 나타남

원인

CloudFront가 HTML 파일을 캐싱하고 있습니다. S3 업로드 후 CloudFront 캐시 무효화를 하지 않으면 계속 이전 버전이 나옵니다.

해결

S3 sync 후 CloudFront 캐시 무효화를 실행합니다.

aws cloudfront create-invalidation \
  --distribution-id E1234567890 \
  --paths "/*" \
  --profile gsr-dev

Lambda에서 DynamoDB AccessDeniedException

IAM

botocore.exceptions.ClientError: AccessDeniedException: User: arn:aws:sts::...assumed-role/... is not authorized to perform: dynamodb:PutItem

원인

Lambda 실행 역할에 DynamoDB 권한이 없습니다. 역할은 있지만 정책에 해당 테이블/액션이 없는 경우입니다.

해결

IAM 역할의 Permission Policy를 확인합니다. dynamodb:PutItem과 Resource에 해당 테이블 ARN(또는 gsr-* 와일드카드)이 포함되어 있어야 합니다. Module 04 참조.

# 빠른 진단: Lambda 역할의 현재 정책 확인
aws iam list-attached-role-policies \
  --role-name gsr-lambda-role \
  --profile gsr-dev

aws iam get-role-policy \
  --role-name gsr-lambda-role \
  --policy-name InlinePolicy \
  --profile gsr-dev

✅ 15가지 오류를 모두 다뤘습니다. 여기에 없는 오류는 CloudWatch Logs (Lambda 콘솔 → 모니터링 → 로그 보기)와 브라우저 콘솔을 먼저 확인하세요. 에러 메시지 전문을 gsr-sso-sample 레포 Issues에 남겨주시면 가이드를 업데이트하겠습니다.