2026년 9월 13일 내용 개정. 공식 문서와 대조해 설명과 예제를 정리했습니다. 설치 버전에 따라 화면과 옵션 이름은 달라질 수 있습니다.
노드가 빨간색으로 바뀌었을 때 설정을 한꺼번에 여러 개 수정하면 원인을 찾기 어렵습니다. 먼저 실패한 실행의 입력을 보존하고, 오류 직전까지 데이터가 어디서 달라졌는지 추적하세요. 이 글은 값 없음, 자료형 불일치, 이전 노드 연결 문제를 구분하는 절차입니다.
이 글에서 확인할 내용: 실패한 입력을 보존하고 값 없음·자료형·아이템 연결·외부 요청 오류를 순서대로 구분합니다. 대표 사진과 본문 사진은 작업 환경 참고용입니다. 대표 사진: Mohammad Rahmani / Unsplash.
1. 재현에 필요한 네 가지 기록
| 기록 | 예 |
|---|---|
| 실패 위치 | Normalize 다음 IF |
| 오류 문구 | 실행 기록의 실제 메시지 |
| 입력 형태 | amount가 숫자가 아닌 빈 문자열 |
| 예상 출력 | 확인 필요 분기로 이동 |
Executions에서 실패 기록을 열어 첫 실패 노드의 Input과 Output을 봅니다. 이전 노드가 성공했더라도 원하는 필드를 출력했다고 보장할 수 없습니다. 이전 실행 데이터를 활용하는 방법은 공식 오류 처리 안내를 참고하세요. 화면과 실행 데이터 보존 범위는 플랜·설정에 따라 달라질 수 있습니다.
2. 값이 사라진 위치 찾기
- 시작 노드에서 필드가 존재하는지 확인합니다.
- HTTP 응답에 body나 data 같은 중첩 객체가 추가됐는지 확인합니다.
- Edit Fields에서 다른 입력 필드를 제외했는지 확인합니다.
- IF의 다른 출력으로 이동했거나 필터가 0건을 반환했는지 확인합니다.
- 고정 데이터가 켜져 오래된 결과를 보고 있지 않은지 확인합니다.
필드 이름은 대소문자를 구분합니다. email과 Email은 다르며, $json.email과 $json.body.email도 다른 경로입니다. 바로 기본값을 넣어 오류를 숨기기 전에 실제 Input의 경로부터 복사하세요.
3. 누락값을 구별하는 진단 실습
가상 데이터 전용 워크플로우에서 Manual Trigger 뒤에 Code를 만들고 아래 입력을 반환합니다. JavaScript / Run Once for All Items 모드입니다.
return [
{ json: { id: "A101", amount: 0 } },
{ json: { id: "A102", amount: "" } },
{ json: { id: "A103", amount: null } },
{ json: { id: "A104" } }
];다음 Code에 아래 코드를 넣습니다. 원문 전체를 로그로 출력하는 대신 문제를 구분하는 최소 필드만 출력합니다.
return $input.all().map((item, index) => {
const hasAmount = Object.prototype.hasOwnProperty.call(item.json, "amount");
const value = item.json.amount;
return {
json: {
id: item.json.id,
hasAmount,
valueType: value === null ? "null" : typeof value,
isBlank: typeof value === "string" && value.trim() === ""
},
pairedItem: { item: index }
};
});| id | hasAmount | valueType | isBlank |
|---|---|---|---|
| A101 | true | number | false |
| A102 | true | string | true |
| A103 | true | null | false |
| A104 | false | undefined | false |
0은 값이 있는 숫자이고, 빈 문자열·null·필드 없음은 서로 다른 상태입니다. 이들을 모두 !value로 검사하면 0까지 누락값으로 분류할 수 있습니다. 업무에서 허용하는 상태를 먼저 정한 뒤 조건을 작성하세요.
4. 아이템 연결 오류는 first()로 덮지 않기
$(‘Sample’).item이 실패했다고 모두 first()로 바꾸면 오류는 사라져도 모든 신청자가 첫 사람의 정보로 바뀔 수 있습니다. 중간 Code에서 새 아이템을 만들거나 여러 건을 합친 뒤에는 연결 관계가 달라질 수 있습니다. 입력·출력 개수와 pairedItem을 확인하고, 데이터 결합에는 고유 ID를 사용합니다.
5. 외부 요청 오류 구분
| 증상 | 점검 방향 |
|---|---|
| 401·403 | 키·권한·계정·인증 방식 확인 |
| 404 | 요청 주소와 리소스 ID 확인 |
| 429 | 호출 제한 또는 할당량과 응답 안내 확인 |
| 시간 초과·5xx | 서버 상태, 제한된 재시도, 중복 처리 위험 확인 |
HTTP 상태 코드만으로 원인을 확정하지 말고 응답 본문의 오류 설명도 확인합니다. 같은 입력으로 한 번씩 재현하며 필드나 설정을 하나만 바꾸세요. 실제 고객 데이터와 API 키가 포함된 로그는 공개 문의글에 그대로 붙여 넣지 않습니다.
6. 알림 워크플로우 검증
별도 워크플로우를 Error Trigger로 시작하고 대상 워크플로우 설정에서 Error workflow로 선택할 수 있습니다. Error Trigger는 자동 실행 실패에서 동작하므로 수동 실행 실패만으로 알림을 시험하면 안 됩니다. Error Trigger 공식 문서에 이 제한이 명시돼 있습니다.
테스트용 자동 트리거와 Stop And Error로 실패를 재현하고, 기록에 워크플로우 이름·실패 단계·실행 식별자가 남는지 확인합니다. 테스트가 끝나면 테스트용 예약 실행을 해제하세요. 알림이 온 사실과 오류가 복구된 사실은 별도로 확인해야 합니다.
함께 읽을 실습
n8n 반복과 Merge: 배치 처리·ID 기준 병합 실습
n8n 워크플로우 안정화: 중복 방지·재시도·예약 실행 점검