n8n 에러 해결 총정리: 설치·웹훅·크리덴셜 트러블슈팅 8가지

워크플로우를 힘들게 짜놓고 저장했는데, 다음 날 실행이 안 되거나 갑자기 빨간 에러 아이콘이 뜬 경험이 있으신가요? n8n은 노드를 연결하는 화면 자체는 직관적이지만, 막상 에러 메시지를 마주치면 무엇부터 확인해야 할지 막막해지는 경우가 많습니다.

이 글에서는 설치, 워크플로우 실행, 노드 연결 단계에서 실제로 자주 보고되는 에러 8가지를 원인과 해결 방법까지 정리했습니다. 모두 n8n 공식 문서와 커뮤니티 포럼(community.n8n.io), GitHub 이슈 트래커에서 확인된 실제 사례를 기반으로 했습니다.

에러 확인 순서부터 잡고 가기

에러 메시지를 정확히 읽지 않고 바로 검색부터 하면 엉뚱한 해결법을 시도하게 됩니다. n8n에서 문제가 생기면 아래 순서로 먼저 확인하는 것이 시간을 가장 아끼는 방법입니다.

• Executions 메뉴: 워크플로우 편집 화면 좌측의 실행 이력에서 실패한 실행을 클릭하면, 어느 노드에서 멈췄는지 빨간색으로 표시되고 상세 에러 메시지를 볼 수 있습니다.
• 셀프호스트(Docker) 로그: docker logs -f n8n으로 실시간 로그를 확인합니다. 컨테이너 이름이 다르면 docker ps로 먼저 이름을 확인하세요.
• 노드 개별 실행: 문제가 의심되는 노드만 따로 ‘Test step’으로 실행해보면 입력 데이터 구조가 예상과 다른지 바로 확인할 수 있습니다.

아직 n8n을 설치하지 않았거나 설치 방식(npx·Docker·클라우드)을 다시 확인하고 싶다면 n8n 설치 방법 총정리 글을 참고하세요. 아래부터는 설치 단계부터 순서대로 자주 나는 에러를 다룹니다.

설치 단계에서 자주 나는 에러 3가지

1. EACCES: permission denied, open ‘/home/node/.n8n/config’

Docker로 n8n을 설치할 때 가장 많이 보고되는 에러입니다. n8n 컨테이너는 root가 아니라 UID 1000(node 계정)으로 실행되는데, 볼륨으로 마운트한 ~/.n8n 디렉터리 소유권이 root로 되어 있으면 쓰기 권한이 없어 발생합니다. n8n GitHub 이슈 트래커(#11102)에도 동일한 사례가 여러 건 보고되어 있습니다.

해결: 호스트에서 볼륨 디렉터리 소유권을 컨테이너 사용자(UID 1000)에 맞춰줍니다.

sudo chown -R 1000:1000 ~/.n8n

2. Error: listen EADDRINUSE :::5678

5678 포트가 이미 다른 프로세스(또는 이전에 종료되지 않은 n8n 컨테이너)에서 사용 중일 때 나는 에러입니다.

해결: docker ps로 기존 컨테이너를 확인해 종료하거나, 포트를 바꿔서 실행합니다.

docker run -it --rm -p 5679:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

3. Error: connect ECONNREFUSED

DB 연결(PostgreSQL은 5432, MySQL은 3306 포트)이나 HTTP Request 노드에서 localhost를 호출할 때 자주 발생합니다. 컨테이너 안에서 localhost는 호스트 PC가 아니라 컨테이너 자기 자신을 가리키기 때문입니다.

해결: DB 환경변수(DB_POSTGRESDB_HOST 등)가 올바른 호스트명을 가리키는지 확인하고, HTTP Request 노드에서는 localhost 대신 host.docker.internal이나 실제 서비스 컨테이너 이름을 사용합니다.

워크플로우가 실행되지 않을 때 (웹훅·트리거 에러)

노드 연결은 멀쩡한데 워크플로우 자체가 시작되지 않는 문제는 대부분 트리거 설정이나 웹훅 활성화 방식에서 비롯됩니다.

4. Workflow Webhook Error: Workflow could not be started!

웹훅으로 워크플로우를 호출했는데 이 메시지가 뜬다면 아래 두 가지를 순서대로 확인하세요.

• 워크플로우가 실제로 Active(활성) 상태인지 — 편집만 하고 저장/활성화를 안 했다면 프로덕션 URL은 동작하지 않습니다.
• Test URL이 아니라 Production URL을 쓰고 있는지 — Test URL은 편집 화면에서 ‘Listen for Test Event’를 누른 뒤 한 번만 유효합니다.

5. No node to start the workflow could be found

워크플로우에 트리거 노드(Webhook, Schedule Trigger, Manual Trigger 등)가 하나도 없거나, 있던 트리거 노드를 실수로 비활성화·삭제했을 때 나는 에러입니다.

해결: 최소 1개의 트리거 노드가 캔버스에 남아있는지 확인합니다. 정기 실행이 목적이라면 Schedule Trigger 노드가 가장 안정적입니다.

6. API로 활성화한 프로덕션 웹훅이 실행되지 않는 경우

n8n 커뮤니티 포럼과 확인된 이슈에 따르면, REST API로 워크플로우를 활성화(activate)하면 웹훅 경로(path) 등록이 제대로 안 되는 경우가 보고되어 있습니다 — 엔드포인트가 200 OK는 반환하지만 실제 실행은 되지 않는 형태입니다. UI 에디터에서 저장 후 활성화하면 이 경로 등록이 정상적으로 이뤄집니다.

해결: 워크플로우를 한 번 n8n 편집 화면에서 열어 활성 토글을 껐다 켠 뒤 저장합니다. 이후 실전 시나리오별 노드 연결 순서가 궁금하다면 n8n 워크플로우 예제 5가지도 함께 참고하면 좋습니다.

노드 연결·크리덴셜에서 나는 에러

7. Code 노드에서 undefined / this.getCredentials is not a function

Code 노드에서 이전 노드의 데이터를 참조했는데 결과가 undefined로 나오는 경우, 대부분 참조하는 필드명이 실제 입력 데이터 구조와 다르기 때문입니다. 노드마다 매 실행마다 데이터 구조가 달라질 수 있어(배열이 비어있는 경우 등) 방어 코드가 필요합니다.

또한 Code 노드 안에서 this.getCredentials()나 $getCredentials()로 크리덴셜을 직접 불러오려 하면 지원되지 않는 함수라는 에러가 납니다 — Code 노드는 인증된 API 호출을 직접 지원하지 않으므로, 인증이 필요한 요청은 HTTP Request 노드로 분리해야 합니다.

해결: Code 노드 상단에 console.log(JSON.stringify($input.all()))로 입력 데이터 구조를 먼저 찍어보고, 옵셔널 체이닝(item.json?.field)으로 안전하게 참조합니다.

8. Authorization failed – please check your credentials (401)

크리덴셜을 분명히 맞게 넣었는데도 401이 반복된다면 아래 순서로 좁혀갑니다.

1. 해당 API 키를 curl이나 Postman으로 n8n 밖에서 먼저 테스트해 키 자체가 유효한지 확인
2. 서비스 대시보드에서 키가 활성 상태인지, 필요한 스코프(권한)가 부여됐는지 확인
3. 복사·붙여넣기 과정에서 숨은 공백/개행 문자가 섞였을 수 있으니 n8n 크리덴셜 화면에 다시 직접 입력
4. 그래도 안 되면 기존 키를 폐기하고 새 키를 발급받아 재시도

크리덴셜을 안전하게 저장·관리하는 기본기가 아직 안 잡혀 있다면 n8n 보안 설정법 글에서 셀프호스트 운영자 체크리스트를 함께 확인하세요.

메모리·성능 관련 에러 (Exit 137, 실행 지연)

워크플로우 자체는 문제가 없는데 컨테이너가 갑자기 재시작되거나 실행이 멈춰버리는 경우, 대부분 메모리 부족(OOM)이 원인입니다.

Exit code 137

컨테이너 프로세스가 메모리 부족으로 강제 종료됐다는 신호입니다. 대용량 JSON을 여러 노드에서 반복 가공하거나, 이미지·파일 처리 노드를 많이 쓰는 워크플로우에서 자주 나타납니다.

해결: docker stats n8n으로 실시간 메모리 사용량을 먼저 확인하고, Docker Desktop이나 docker-compose의 메모리 제한을 올리거나 Node.js 힙 크기를 늘립니다.

NODE_OPTIONS="--max-old-space-size=2048"

워크플로우 개수가 많아지고 동시 실행이 잦아졌다면, 단일 프로세스 대신 실행 큐를 분리하는 Queue 모드(Redis + 워커 프로세스 구조)로 전환하는 것도 장기적인 해결책입니다.

에러를 미리 잡는 법 — Error Workflow 설정

에러가 나고 나서 뒤늦게 발견하는 대신, n8n의 Error Trigger 노드로 별도의 ‘에러 워크플로우’를 만들어두면 실패를 실시간으로 알림받을 수 있습니다.

• 새 워크플로우를 하나 만들고 트리거로 Error Trigger 노드를 추가합니다.
• 뒤에 Slack, 이메일, Discord 등 알림 노드를 연결합니다.
• 대상 워크플로우의 Settings에서 ‘Error Workflow’ 항목에 방금 만든 워크플로우를 지정합니다.
• 중요한 노드에는 ‘Retry On Fail’ 옵션을 켜두면 일시적인 네트워크 오류는 자동으로 재시도됩니다.

이렇게 설정해두면 실제로 문제가 생겼을 때 Executions 로그를 매번 들여다보지 않아도, 메시지 한 통으로 어떤 워크플로우가 왜 실패했는지 바로 알 수 있습니다. 자동화를 여러 개 운영하기 시작했다면 커뮤니티에 공개된 템플릿 구조를 참고하는 것도 도움이 됩니다 — n8n 커뮤니티 템플릿 활용법에서 초보자용 추천 워크플로우도 함께 확인해보세요.

자주 묻는 질문

핵심 요약

• 에러가 나면 검색 전에 Executions 로그와 docker logs로 원문 메시지부터 확인한다.
• 설치 단계는 권한(EACCES)·포트 충돌·DB 연결이, 실행 단계는 웹훅 활성화 방식이 주요 원인이다.
• Error Trigger 노드로 알림 워크플로우를 미리 만들어두면 문제를 훨씬 빨리 발견할 수 있다.

---