CH05 · 모니터링 & 사용자 관리

5-2. 에러 모니터링 — AI가 원인 분석과 해결책까지

이전 클립에서 신규 워크플로우 감지 기능을 만들었습니다. 이번에는 운영에서 가장 부담스러운 주제, 에러 모니터링을 다룹니다.

워크플로우가 잘 돌다가 갑자기 실패합니다. n8n 웹 UI의 실행 이력을 열면 영어 에러 메시지와 기술 용어가 잔뜩 나옵니다. 비개발자에게는 거의 암호입니다. 이 문제를 AI가 해결합니다.

1. 에러 메시지가 어려운 이유

n8n에서 자주 만나는 에러 메시지의 예시입니다.

401 Unauthorized - Invalid API Key
ETIMEDOUT: connection timed out
Cannot read properties of undefined (reading 'email')

개발자라면 즉시 원인을 파악합니다. 하지만 "API 키가 만료됐다", "서버 연결이 끊겼다", "데이터 형식이 바뀌었다" 같은 해석은 비개발자에게는 쉽지 않습니다. 더 큰 문제는 어떻게 고치는지 모른다는 점입니다.

2. n8n_executions로 실패 이력 조회

n8n_executions MCP 도구로 워크플로우의 실행 이력을 조회할 수 있습니다. 특히 status 필터를 적용하면 실패한 실행만 골라서 볼 수 있습니다.

Claude는 이 실행 이력을 읽고 에러 메시지를 분석한 뒤, 한국어로 원인과 해결책을 정리합니다.

3. 에러 분류 체계

n8n 에러는 크게 네 가지로 분류됩니다. 분류를 알면 Claude의 분석 결과를 더 빠르게 이해할 수 있습니다.

연결 에러

401 Unauthorized, 403 Forbidden, ECONNREFUSED. API 키 만료, URL 변경, 외부 서비스 다운이 원인입니다. 크레덴셜 갱신·URL 확인·서비스 상태 점검이 필요합니다.

데이터 에러

Cannot read properties of undefined, TypeError. 외부 API 응답 형식 변경, 필수 필드 누락이 원인입니다. 데이터 구조 확인과 예외 처리 노드 추가가 필요합니다.

로직 에러

No items returned, Switch node has no matching case. IF/Switch 분기 오류, 빈 결과 처리 누락이 원인입니다. 조건식 수정과 default 분기 추가가 필요합니다.

리소스 에러

ETIMEDOUT, Request Entity Too Large, heap out of memory. 타임아웃, 데이터 크기 초과, 메모리 부족이 원인입니다. 타임아웃 값 증가·배치 처리·서버 사양 점검이 필요합니다.

4. 실습 — "이번 주 실패한 워크플로우를 분석해줘"

터미널에서 Claude Code를 열고 다음과 같이 지시합니다.

이번 주에 실패한 워크플로우 실행 기록을 분석해줘.
각 에러의 원인을 분류하고, 해결 방법을 한국어로 알려줘.

Claude가 수행하는 작업입니다.

STEP 1

n8n_executions로 실패 실행 이력 조회

STEP 2

각 에러 메시지를 네 가지 분류 중 어디에 해당하는지 판단

STEP 3

워크플로우별 그룹핑으로 반복 실패 패턴 확인

STEP 4

원인과 해결책을 한국어로 정리해 리포트 생성

결과는 다음과 같이 나옵니다.

이번 주 에러 분석 리포트 (총 5건) [마케팅 주간 리포트] - 3회 실패 - 분류: 연결 에러 - 에러: 401 Unauthorized - Invalid API Key - 원인: Google Sheets 크레덴셜의 OAuth 토큰이 만료된 것으로 보입니다. - 해결: n8n 크레덴셜 설정에서 Google Sheets 인증을 다시 연결하세요. [고객 문의 자동 응답] - 2회 실패 - 분류: 데이터 에러 - 에러: Cannot read properties of undefined (reading 'email') - 원인: 웹훅으로 들어오는 데이터에 email 필드가 누락된 요청이 있습니다. - 해결: IF 노드로 email 필드 존재 여부를 먼저 확인하도록 수정하세요.

에러 메시지만 봐서는 알 수 없던 원인과 해결책이, AI 분석을 통해 비개발자도 이해할 수 있는 한국어로 정리됩니다.

5. autofix — AI가 직접 수정까지

원인 분석에서 한 단계 더 나아갈 수 있습니다. n8n_autofix_workflow 도구로 Claude가 에러를 직접 수정하도록 시도할 수 있습니다.

예를 들어 "고객 문의 자동 응답" 워크플로우에서 email 필드 누락 에러가 반복된다면 다음과 같이 지시합니다.

"고객 문의 자동 응답" 워크플로우의 email 필드 누락 에러를 자동 수정해줘.

Claude는 n8n_autofix_workflow를 호출하여 워크플로우를 분석하고 데이터 검증 로직 추가를 시도합니다. 자동 수정이 성공하면 바로 적용되고, 어려운 경우에는 수동으로 수정할 구체적인 방안을 제시합니다.

모든 에러를 AI가 자동으로 고칠 수는 없습니다. 크레덴셜 갱신처럼 사람의 조작이 필요한 경우도 있습니다. 하지만 "무엇을 해야 하는지"를 정확히 알려주는 것만으로도 운영 부담이 크게 줄어듭니다.

6. ops-manager 모듈에 에러 분석 등록

## 에러 모니터링

트리거: "에러 분석", "실패한 워크플로우", "에러 리포트"

절차:
1. n8n_executions로 실패 실행 이력 조회 (기간 지정 가능)
2. 에러 메시지 분석 → 연결/데이터/로직/리소스 에러로 분류
3. 워크플로우별 그룹핑, 반복 실패 패턴 확인
4. 원인 분석 + 한국어 해결책 정리
5. autofix 가능한 항목은 자동 수정 시도, 불가능한 항목은 수동 수정안 제시

7. 마무리

★ 핵심. 에러 분류 4종(연결·데이터·로직·리소스)과 autofix를 결합하면, 비개발자도 에러를 즉시 이해하고 일부는 자동으로 고칠 수 있습니다.

다음 클립에서는 워크플로우가 아닌 사람을 관리하는 방법을 다룹니다. 퇴사자 인계와 휴면 유저 정리 프로세스를 만들겠습니다.

다음 클립

5-3. 사용자 관리 — 퇴사자 인계, 휴면 유저 정리

이어보기 →