웹 요청 장애 진단: DNS·HTTP·CORS·인증·캐시 문제를 계층별로 찾기

진단 전에 증거부터 남기기

문제가 발생하면 코드를 바로 수정하기보다 먼저 재현 조건을 기록합니다.

발생 URL:
발생 시각:
브라우저:
로그인 여부:
요청 Method:
Network Status:
Console 오류:
재현 순서:
정상 기대 결과:
실제 결과:

이 정보를 먼저 남기면 수정 후 같은 조건에서 다시 확인할 수 있습니다.

“아까는 안 됐는데 지금은 됩니다”로 끝나지 않고 무엇이 바뀌었는지 추적할 수 있습니다.

1단계 URL과 DNS

가장 먼저 요청 주소 자체가 맞는지 확인합니다.

scheme
host
port
path
query

도메인 이름을 찾지 못한다면 HTTP 상태 코드를 보기 전에 DNS를 확인합니다.

Windows에서는 필요할 때 다음 명령을 사용할 수 있습니다.

nslookup example.com

대표 증상

도메인 이름 해석 실패
ERR_NAME_NOT_RESOLVED 계열 메시지
HTTP Status 없음

확인 순서

1. host 오타 확인
2. DNS 조회 가능 여부 확인
3. 다른 네트워크에서도 같은지 확인
4. 로컬 hosts 설정이나 VPN·사내 DNS 영향 확인

환경에 따라 원인은 달라질 수 있으므로 브라우저 오류 문구 하나만 보고 DNS 서버 문제라고 단정하지 않습니다.

2단계 서버 연결과 TLS

DNS가 성공해도 서버가 해당 포트에서 연결을 받지 않으면 접속할 수 없습니다.

로컬 개발 환경에서는 개발 서버를 실행하지 않은 경우가 대표적입니다.

http://localhost:5173
↓
서버 미실행
↓
연결 거부

HTTPS에서는 인증서와 TLS 연결도 확인합니다.

대표 증상

connection refused
connection timeout
certificate warning
TLS handshake 관련 오류

확인 순서

1. 대상 host와 port 확인
2. 서버 프로세스 실행 여부 확인
3. 방화벽·프록시·VPN 영향 확인
4. HTTPS 인증서 경고 확인
5. HTTP Status가 실제로 존재하는지 확인

HTTP Status가 없다면 서버 애플리케이션 코드까지 요청이 도달하지 않았을 가능성을 먼저 생각합니다.

3단계 HTTP 응답

Network에서 Status Code가 보인다면 HTTP 요청과 응답 단계까지 진행된 것입니다.

404

서버 도달
→ 요청한 리소스 또는 Route를 찾지 못함

확인할 항목입니다.

Request URL
path
배포된 route
정적 파일 위치
API endpoint

500

서버 도달
→ 서버 처리 중 오류

프론트엔드에서는 요청 Body·Query·Header가 API 계약과 맞는지 확인합니다.

서버 로그에 접근할 수 있다면 같은 요청 시각의 서버 오류도 확인합니다.

200인데 화면이 이상함

HTTP 요청 자체는 성공했지만 프론트엔드 처리 단계에서 실패할 수 있습니다.

Network 200
↓
응답 JSON 확인
↓
Console 오류 확인
↓
렌더링 로직 확인

200만 보고 전체 기능이 정상이라고 판단하면 안 됩니다.

4단계 인증과 권한

API가 401이나 403을 반환하면 인증 정보를 봅니다.

401

대표적으로 인증 정보가 없거나 유효하지 않은 상황에 사용됩니다.

확인할 항목입니다.

Cookie
Authorization Header
Token 만료
Session 존재 여부
로그인 상태

403

대표적으로 인증된 사용자에게 해당 작업 권한이 없는 상황에 사용됩니다.

사용자 식별 성공 가능
↓
권한 검사 실패
↓
403

다만 서버 구현에 따라 401과 403 정책이 다를 수 있으므로 API 문서와 서버 로직을 함께 확인합니다.

5단계 CORS와 preflight

브라우저 Console에 CORS 관련 메시지가 보이면 Network에서 실제 요청 흐름을 확인합니다.

확인할 항목

Request Origin
OPTIONS 요청 존재 여부
Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers
Access-Control-Allow-Credentials

preflight가 실패한 경우 실제 POST나 PATCH 요청이 시작되지 않을 수 있습니다.

Network에 API 요청이 보였다고 해서 JavaScript가 응답을 읽을 수 있다는 의미도 아닙니다.

CORS는 서버 응답과 브라우저 정책을 함께 봐야 합니다.

잘못된 접근

CORS 오류
→ 브라우저 보안 기능 끄기
→ 해결 처리

이 방법은 개발 환경에서 증상을 숨길 뿐 운영 문제를 해결하지 못합니다.

6단계 Cookie 전송

로그인은 성공했는데 이후 요청에서 인증이 풀린다면 Cookie 전송 조건을 확인합니다.

Cookie Domain
Path
Secure
SameSite
credentials 옵션
HTTPS 여부
브라우저의 제3자 Cookie 정책

교차 출처 fetch에서 Cookie가 필요하다면 다음과 같은 설정이 필요한 구조가 있을 수 있습니다.

fetch('https://api.example.com/tasks', {
  credentials: 'include'
});

하지만 fetch 설정만 추가한다고 끝나지 않습니다.

서버 CORS 설정과 Cookie 속성도 모두 조건을 만족해야 합니다.

7단계 캐시

수정한 코드가 반영되지 않거나 이전 API 응답이 보이면 캐시 계층을 확인합니다.

먼저 브라우저 HTTP 캐시를 봅니다.

Cache-Control
ETag
Last-Modified
Status 304
Size

Disable cache를 켠 상태와 끈 상태를 비교할 수도 있습니다.

그다음 필요할 때 다른 캐시를 분리합니다.

CDN
Service Worker
Next.js Cache
TanStack Query
애플리케이션 메모리

한 계층의 캐시를 지웠다고 모든 캐시가 사라지는 것은 아닙니다.

8단계 프론트엔드 실행

네트워크가 정상인데 화면이 동작하지 않는다면 프론트엔드 실행 문제를 확인합니다.

Network 200
Response 데이터 정상
↓
Console 확인
↓
JavaScript 오류
DOM 렌더링 오류
상태 업데이트 오류
이벤트 연결 오류

브라우저 메인 스레드가 긴 동기 작업으로 막혀 있는지도 확인할 수 있습니다.

클릭 안 됨
스크롤 끊김
화면 멈춤
↓
CPU 사용량·Performance 확인
↓
긴 JavaScript 작업 여부 확인

이 단계는 JavaScript·React 과정에서 더 자세히 다룹니다.

대표 장애 시나리오

페이지 자체가 열리지 않음

URL 확인
→ DNS 확인
→ 연결 여부
→ TLS
→ HTTP Status 존재 여부

404나 500이 보이면 DNS보다 HTTP 단계부터 확인합니다.

API만 실패함

Network 요청 존재?
→ Status 확인
→ Request Body/Header 확인
→ 401/403 여부
→ CORS 여부
→ Response 확인

로그인 후 바로 풀림

로그인 응답 확인
→ Set-Cookie 확인
→ Application Cookie 확인
→ 다음 Request의 Cookie 확인
→ Domain/Path/Secure/SameSite
→ credentials/CORS

CORS 오류

origin 확인
→ OPTIONS 확인
→ 서버 Allow Header 확인
→ credentials 여부
→ 실제 요청 진행 여부

배포 후 이전 화면이 보임

요청한 JS/CSS URL 확인
→ Cache-Control
→ 304
→ 파일 해시
→ CDN/Service Worker 등 추가 캐시

Network는 200인데 화면이 비어 있음

Response 데이터 확인
→ Console 오류
→ JavaScript 실행
→ 렌더링 로직
→ 상태 처리

최종 진단 체크리스트

문제가 발생하면 다음 순서를 기본값으로 사용합니다.

1. 증상과 재현 조건 기록
2. 요청 URL 확인
3. DNS·연결·TLS 확인
4. HTTP Status 확인
5. Request·Response 내용 확인
6. 401·403 인증/권한 확인
7. CORS·preflight 확인
8. Cookie 전송 조건 확인
9. 캐시 계층 확인
10. Console과 프론트엔드 실행 확인
11. 수정
12. 같은 조건으로 재검증

모든 문제를 항상 1번부터 끝까지 확인할 필요는 없습니다.

증상에 따라 가능한 계층을 빠르게 좁히되 확인되지 않은 원인을 사실처럼 단정하지 않는 것이 중요합니다.

흔한 진단 실수

오류 메시지를 검색하고 첫 해결책을 바로 적용합니다

같은 메시지라도 원인이 다를 수 있습니다.

먼저 자신의 Request URL·Header·Status·환경을 확인합니다.

여러 설정을 한꺼번에 바꿉니다

무엇이 해결에 영향을 줬는지 알기 어려워집니다.

가능하면 한 번에 하나의 원인을 검증합니다.

정상 응답과 정상 화면을 같은 것으로 봅니다

Network와 Console을 분리해서 봅니다.

개발 환경에서 우회되면 해결된 것으로 봅니다

CORS 비활성화, 인증 검사 제거, cache 강제 해제 같은 방법은 원인 확인에 임시로 사용할 수 있어도 운영 해결책이 아닐 수 있습니다.

독자 질문과 실전 확인

독자 질문

API 응답은 200인데 화면이 비어 있다면 DNS부터 다시 조사해야 할까요?

웹 개발 사례

TaskFlow 목록 API의 실제 요청이 200이고 응답 Body에 예상 데이터가 있다면 HTTP 응답 이후의 JSON 처리·상태 반영·렌더링·Console 오류로 범위를 좁힐 수 있습니다. 반대로 Status가 없는 실패라면 URL·DNS·연결·TLS 쪽 증거를 봅니다.

직접 확인할 문제

사례 A: Status 없음, ERR_NAME_NOT_RESOLVED. 사례 B: OPTIONS 실패, 실제 POST 없음. 사례 C: API 200, Body 정상, Console TypeError. 각 사례의 우선 확인 계층과 수정 후 다시 볼 관찰값을 적으세요.

예상 결과와 판단

A는 host와 이름 조회, B는 Origin·preflight 응답 허용 항목과 실제 요청 유무, C는 오류 스택과 화면 반영 로직이 우선입니다. 같은 URL·로그인 상태·브라우저 조건으로 재검증하고 Status·Console·화면 결과를 함께 남깁니다. 단일 증상만으로 최종 원인을 확정하지 않습니다.

검증 범위

A·B·C는 학습용 가상 사례입니다. 실제 장애를 재현하거나 수정·재검증한 결과가 아니며 운영 로그와 서버 설정은 확인하지 않았습니다.

다음 학습: 과정 종료 뒤 실제 URL의 장애를 다루는 배포·서버 과정으로 확장하고, 논리 구조 학습은 이산수학 과정으로 이어갑니다.

학습 완료 체크리스트

• DNS·연결·TLS·HTTP 오류를 계층별로 구분할 수 있습니다.
• 401·403·CORS 문제를 같은 문제로 보지 않습니다.
• Cookie가 안 전송될 때 확인할 조건을 알고 있습니다.
• 304와 브라우저 캐시를 오류로 오해하지 않습니다.
• Network 200 이후에도 프론트엔드 오류가 있을 수 있음을 이해했습니다.
• 수정 전에 재현 조건과 증거를 남길 수 있습니다.
• 수정 후 같은 조건에서 재검증하는 습관을 설명할 수 있습니다.

cs-step-06-process-memory

사용자 URL 입력
↓
URL 해석
↓
DNS
↓
서버 연결
↓
TLS
↓
HTTP 요청
├─ Cookie
├─ Authorization
└─ Origin
↓
서버 인증·권한
↓
HTTP 응답
├─ Status
├─ Response Headers
└─ Body
↓
브라우저 CORS 검사
↓
HTTP 캐시 판단
↓
JavaScript 실행
↓
화면 렌더링

브라우저 메모리
브라우저 저장소
서버 메모리
영속 데이터베이스

URL·DNS
→ 주소·nslookup

연결·TLS
→ 브라우저 연결 오류·인증서

HTTP
→ Network Status·Headers·Response

인증
→ Cookie·Authorization·401·403

CORS
→ Origin·OPTIONS·Access-Control-Allow-*

캐시
→ Cache-Control·ETag·304

프론트엔드 실행
→ Console·렌더링·상태

화면이 안 됨
→ 원인을 추측
→ 여러 설정을 한꺼번에 수정

증상 기록
→ 어느 계층까지 성공했는지 확인
→ 실패 계층 좁히기
→ 최소 수정
→ 같은 조건에서 재검증

✓ 1. 브라우저·HTTP 요청/응답
✓ 2. DNS·TCP·TLS
✓ 3. 쿠키·세션·토큰·CORS
✓ 4. CSRF·XSS
✓ 5. HTTP 캐시
✓ 6. 프로세스·스레드·메모리
→ 7. 통합 장애 진단 완료

cs-step-07-troubleshooting-final

URL·DNS·TCP/TLS·HTTP 요청 경로
Request·Response 관찰 항목
인증·권한·CORS 경계
CSRF·XSS 보안 경계
HTTP 캐시 흐름
브라우저·서버 상태 위치
계층별 장애 진단 체크리스트