async/await에서 try/catch를 써도 UnhandledRejection이 나요.

await 없이 반환된 Promise를 놓치거나, 이벤트 핸들러에서 async 함수를 호출만 하고 반환값을 연결하지 않은 경우가 흔합니다. 최상위에 .catch를 두거나 void 연산자로라도 연결을 검토하세요.

Promise 체인에서 스택이 짧게 나와요.

비동기 경계마다 스택이 끊깁니다. async 스택을 지원하는 브라우저/Node 옵션과 소스맵을 켜고, 로그에 상관 ID를 붙이면 추적이 쉬워집니다.

setTimeout 안의 에러는 왜 상위로 안 올라가나요?

별도 태스크 큐에서 실행되어 동기 try/catch 밖입니다. 콜백 내부에서 처리하거나 Promise로 감싸 일관된 에러 경로를 만듭니다.

프로덕션에서 비동기 에러를 어떻게 남기나요?

전역 unhandledRejection 핸들러·Sentry 등으로 수집하고, PII를 마스킹합니다. 재시도 가능한 오류와 치명 오류를 구분해 알려주세요.

JavaScript 비동기 디버깅 실전 사례 | Promise 체인 에러 추적하기

2026년 3월 30일 · 20분 읽기 · 수정 2026년 4월 7일 중급

이 글의 핵심

JavaScript 비동기 코드에서 발생한 에러를 추적하고 해결한 실전 사례. Promise 체인, async/await, 에러 핸들링, 스택 트레이스 분석 방법을 다룹니다.

들어가며

“Unhandled Promise Rejection”은 JavaScript 개발자가 가장 자주 보는 에러 중 하나입니다. 이 글에서는 복잡한 비동기 코드에서 에러를 추적하고 해결한 실전 사례를 공유합니다. 일상에 빗대면, 전화를 돌려주기만 하고 끊지 않은 통화와 비슷합니다. 어디선가 예외가 났는데 호출자에게 돌아오는 길이 끊겨 있으면 “처리 안 된 약속”으로 남습니다.

이 글을 읽으면

Promise 에러가 사라지는 이유를 이해합니다
비동기 스택 트레이스를 추적하는 방법을 배웁니다
async/await에서 에러 처리 패턴을 익힙니다
프로덕션 환경에서 에러 모니터링하는 법을 습득합니다

실전 경험에서 배운 교훈

이 기술을 실무 프로젝트에 처음 도입했을 때, 공식 문서만으로는 알 수 없었던 많은 함정들이 있었습니다. 특히 프로덕션 환경에서 발생하는 엣지 케이스들은 로컬 개발 환경에서는 재현조차 되지 않았죠.

가장 어려웠던 점은 성능 최적화였습니다. 처음엔 “동작만 하면 되겠지”라고 생각했지만, 실제 사용자 트래픽이 몰리면서 병목 지점들이 하나씩 드러났습니다. 특히 데이터베이스 쿼리 최적화, 캐싱 전략, 에러 핸들링 구조 등은 여러 번의 장애를 겪으면서 개선해 나갔습니다.

이 글에서는 그런 시행착오를 통해 얻은 실전 노하우와, “이렇게 하면 안 된다”는 교훈들을 함께 정리했습니다. 특히 트러블슈팅 섹션은 실제 장애 대응 경험을 바탕으로 작성했으니, 비슷한 문제를 마주했을 때 참고하시면 도움이 될 것입니다.

1. 문제: 간헐적 Unhandled Rejection

증상

문제의 핵심은 에러 메시지 자체가 아니라, 어느 요청·어느 사용자 흐름에서 터졌는지 추적하기 어렵다는 점이었습니다. 프로덕션 로그에 간헐적으로 아래와 같은 기록이 남았습니다.

(node:12345) UnhandledPromiseRejectionWarning: Error: Database connection failed
    at Database.connect (database.js:45:15)
(node:12345) UnhandledPromiseRejectionWarning: Unhandled promise rejection.

특징

재현 불가: 로컬에서는 발생 안 함
간헐적: 하루에 5-10번 발생
정보 부족: 어디서 호출했는지 알 수 없음

2. 증상 분석: 에러가 사라진다

문제 코드

// API 엔드포인트
app.get('/users/:id', (req, res) => {
  getUserData(req.params.id)
    .then(user => {
      res.json(user);
    });
  // 🚨 .catch()가 없음!
});
async function getUserData(id) {
  const user = await db.query('SELECT * FROM users WHERE id = ?', id);
  
  if (!user) {
    throw new Error('User not found'); // 💥 에러가 사라짐!
  }
  
  return user;
}

왜 에러가 사라지나?

// Promise 체인
getUserData(id)           // Promise 생성
  .then(user => {         // 성공 핸들러만 있음
    res.json(user);
  });
  // .catch() 없음 → 에러가 처리되지 않음!
// 에러 발생 시
// 1. getUserData에서 throw
// 2. Promise가 rejected 상태가 됨
// 3. .catch()가 없으므로 Unhandled Rejection
// 4. Node.js가 경고만 출력하고 계속 실행

3. Promise 체인 추적

스택 트레이스 개선

// Node.js 플래그로 긴 스택 트레이스 활성화
// package.json
{
  "scripts": {
    "start": "node --trace-warnings --async-stack-traces server.js"
  }
}

결과

(node:12345) UnhandledPromiseRejectionWarning: Error: User not found
    at getUserData (user_service.js:23:11)
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
    at async /home/app/routes/users.js:15:18  ← 호출 위치!

발견: `routes/users.js:15` 에서 에러 처리 누락!

4. 근본 원인: 에러 핸들러 누락

문제 패턴

// 패턴 1: .catch() 누락
promise.then(result => {
  console.log(result);
}); // 🚨 .catch() 없음
// 패턴 2: async 함수에서 try-catch 누락
async function handler(req, res) {
  const data = await fetchData(); // 🚨 에러 처리 없음
  res.json(data);
}
// 패턴 3: 중간에 에러 삼키기
promise
  .then(result => processResult(result))
  .catch(err => {
    console.log(err); // 로그만 찍고 끝
    // 🚨 에러를 다시 throw하지 않음
  })
  .then(result => {
    // 여기서 result는 undefined
  });

5. 해결 1: async/await로 전환

개선 코드

// Before: Promise 체인
app.get('/users/:id', (req, res) => {
  getUserData(req.params.id)
    .then(user => {
      res.json(user);
    });
  // .catch() 누락
});
// After: async/await + try-catch
app.get('/users/:id', async (req, res) => {
  try {
    const user = await getUserData(req.params.id);
    res.json(user);
  } catch (err) {
    console.error('Error fetching user:', err);
    res.status(500).json({ error: 'Internal server error' });
  }
});

장점

에러 처리가 명확함
스택 트레이스가 더 읽기 쉬움
동기 코드처럼 읽힘

6. 해결 2: 전역 에러 핸들러

Node.js 전역 핸들러

// 모든 Unhandled Rejection 캐치
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
  
  // 에러 로깅 서비스로 전송
  errorLogger.log({
    type: 'unhandledRejection',
    reason: reason,
    stack: reason.stack,
    timestamp: new Date().toISOString(),
  });
  
  // 프로덕션에서는 프로세스 종료 고려
  // process.exit(1);
});
// Uncaught Exception도 처리
process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', err);
  errorLogger.log({
    type: 'uncaughtException',
    error: err.message,
    stack: err.stack,
  });
  
  // 프로세스 종료 (상태가 불안정할 수 있음)
  process.exit(1);
});

Express 에러 미들웨어

// 모든 라우트 핸들러를 래핑
function asyncHandler(fn) {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}
// 사용
app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await getUserData(req.params.id);
  res.json(user);
  // 에러 발생 시 자동으로 next(err) 호출
}));
// 에러 핸들러
app.use((err, req, res, next) => {
  console.error('Error:', err);
  res.status(500).json({ error: err.message });
});

7. 해결 3: 에러 경계 패턴

Service Layer에서 에러 래핑

class UserService {
  async getUser(id) {
    try {
      const user = await db.query('SELECT * FROM users WHERE id = ?', id);
      
      if (!user) {
        throw new NotFoundError(`User ${id} not found`);
      }
      
      return user;
    } catch (err) {
      // 데이터베이스 에러를 도메인 에러로 변환
      if (err.code === 'ECONNREFUSED') {
        throw new ServiceUnavailableError('Database connection failed');
      }
      throw err;
    }
  }
}
// 커스텀 에러 클래스
class NotFoundError extends Error {
  constructor(message) {
    super(message);
    this.name = 'NotFoundError';
    this.statusCode = 404;
  }
}
class ServiceUnavailableError extends Error {
  constructor(message) {
    super(message);
    this.name = 'ServiceUnavailableError';
    this.statusCode = 503;
  }
}

에러 타입별 처리

app.use((err, req, res, next) => {
  if (err instanceof NotFoundError) {
    return res.status(404).json({ error: err.message });
  }
  
  if (err instanceof ServiceUnavailableError) {
    return res.status(503).json({ error: 'Service temporarily unavailable' });
  }
  
  // 예상치 못한 에러
  console.error('Unexpected error:', err);
  res.status(500).json({ error: 'Internal server error' });
});

8. 모니터링: Sentry 연동

Sentry 설정

const Sentry = require('@sentry/node');
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  integrations: [
    new Sentry.Integrations.Http({ tracing: true }),
  ],
});
// Express 미들웨어
app.use(Sentry.Handlers.requestHandler());
app.use(Sentry.Handlers.tracingHandler());
// 에러 핸들러 (라우트 뒤에 배치)
app.use(Sentry.Handlers.errorHandler());

커스텀 컨텍스트 추가

app.get('/users/:id', async (req, res) => {
  Sentry.setContext('user_request', {
    userId: req.params.id,
    ip: req.ip,
  });
  
  try {
    const user = await getUserData(req.params.id);
    res.json(user);
  } catch (err) {
    Sentry.captureException(err);
    res.status(500).json({ error: 'Internal server error' });
  }
});

9. 실전 패턴 모음

패턴 1: Promise.all 에러 처리

// ❌ 나쁜 패턴: 하나 실패하면 전체 실패
const results = await Promise.all([
  fetchUser(1),
  fetchUser(2),
  fetchUser(3),
]);
// ✅ 좋은 패턴: 개별 에러 처리
const results = await Promise.all([
  fetchUser(1).catch(err => ({ error: err })),
  fetchUser(2).catch(err => ({ error: err })),
  fetchUser(3).catch(err => ({ error: err })),
]);
// 성공한 것만 필터링
const users = results.filter(r => !r.error);
// ✅ 더 좋은 패턴: Promise.allSettled
const results = await Promise.allSettled([
  fetchUser(1),
  fetchUser(2),
  fetchUser(3),
]);
const users = results
  .filter(r => r.status === 'fulfilled')
  .map(r => r.value);

패턴 2: 타임아웃 처리

function withTimeout(promise, ms) {
  return Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Timeout')), ms)
    ),
  ]);
}
// 사용
try {
  const data = await withTimeout(fetchData(), 5000);
} catch (err) {
  if (err.message === 'Timeout') {
    console.error('Request timed out');
  }
}

패턴 3: 재시도 로직

async function retry(fn, maxAttempts = 3, delay = 1000) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (attempt === maxAttempts) {
        throw err;
      }
      
      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
      delay *= 2; // Exponential backoff
    }
  }
}
// 사용
const data = await retry(() => fetchData(), 3, 1000);

마무리

JavaScript 비동기 에러 디버깅의 핵심:

모든 Promise에 .catch() 또는 try-catch 추가
전역 핸들러로 누락된 에러 캐치
에러 모니터링 도구 (Sentry) 활용
async/await로 가독성과 에러 처리 개선 핵심: “에러가 발생하지 않을 것”이라 가정하지 말고, 항상 에러 처리를 추가하세요.

FAQ

Q1. Promise 체인 vs async/await 중 뭘 써야 하나요? async/await를 권장합니다. 에러 처리가 명확하고 스택 트레이스가 더 읽기 쉽습니다. Q2. try-catch를 모든 함수에 추가해야 하나요? 최상위 핸들러(Express 미들웨어, 전역 핸들러)에서 처리하고, 비즈니스 로직에서는 필요한 곳만 추가하세요. Q3. Unhandled Rejection이 발생하면 프로세스를 종료해야 하나요? Node.js 15+에서는 기본적으로 종료됩니다. 프로덕션에서는 PM2 등으로 자동 재시작을 설정하세요.

키워드

JavaScript, 비동기, Promise, async/await, Unhandled Rejection, 에러 처리, 디버깅, Sentry, 실전 사례, Node.js

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「JavaScript 비동기 디버깅 실전 사례 | Promise 체인 에러 추적하기」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「JavaScript 비동기 디버깅 실전 사례 | Promise 체인 에러 추적하기」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

이 글에서 다루는 키워드 (관련 검색어)

JavaScript, 비동기, Promise, async/await, 디버깅, 에러 처리, 실전 사례 등으로 검색하시면 이 글이 도움이 됩니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.