홈›도서›하루 30분 n8n ④›부록 B — 트러블슈팅 30선

부록 B★☆☆

부록 B — 트러블슈팅 30선

📖 이론20분

"문제는 해결되기 전까지만 문제다."

— 헨리 포드 (Henry Ford, 포드 자동차 창업자)

🎯 오늘의 학습 목표

n8n 운영 중 발생하는 주요 오류를 빠르게 진단하고 해결할 수 있다.

🔴 설치/실행 문제

Q1. docker compose up -d 후 n8n이 바로 죽어요.

bash

docker compose logs n8n --tail=100

Q1 해결

원인: .env 오타, PostgreSQL 미준비, 포트 충돌. 로그 메시지를 확인한 뒤 해당 원인을 수정하고 docker compose restart n8n을 실행합니다.

Q2. HTTPS 설정 후 WebSocket 오류 (실시간 업데이트 안 됨)

nginx

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Q2 해결

Nginx 설정에 위 세 줄을 추가한 뒤 sudo nginx -s reload를 실행하세요. WebSocket 업그레이드 헤더가 없으면 실시간 연결이 차단됩니다.

Q3. '502 Bad Gateway' 오류

bash

docker compose ps && docker compose restart n8n

Q3 해결

n8n 컨테이너가 실행 중인지 확인하세요. 컨테이너가 Exited 상태라면 docker compose logs n8n으로 원인을 파악한 뒤 재시작합니다.

Q4. SSL 인증서 발급 실패

bash

ufw allow 80
# DNS 반영 확인 후 재시도
certbot --nginx -d yourdomain.com

Q4 해결

80번 포트가 열려 있어야 Let's Encrypt 인증 챌린지가 통과됩니다. DNS가 서버 IP를 가리키고 있는지도 nslookup yourdomain.com 으로 확인하세요.

🟡 성능 문제

Q5. 워크플로우가 갑자기 느려졌어요.

bash

docker compose exec postgres psql -U n8n_user n8n_db \
  -c "SELECT COUNT(*) FROM execution_entity;"

Q5 해결

5만 건 이상이면 정리가 필요합니다. .env에 EXECUTIONS_DATA_PRUNE=true 설정 후 재시작하세요.

Q6. RAM이 계속 올라가다가 서버가 재시작돼요.

yaml

services:
  n8n:
    mem_limit: 2g
    memswap_limit: 2g

Q6 해결

docker-compose.yml에 mem_limit을 지정하면 컨테이너가 메모리 한도를 초과할 때 서버 전체가 아닌 컨테이너만 재시작됩니다. 값은 서버 RAM의 60~70% 이내로 설정하세요.

Q7. CPU가 100%에 계속 머물러요.

특정 워크플로우가 무한 루프에 빠졌거나 대용량 데이터를 한 번에 처리하는 경우입니다. Executions 탭에서 Running 상태의 실행을 중단하고, 해당 워크플로우에 Split In Batches 노드를 추가해 처리량을 분산하세요.

Q8. 대용량 JSON 처리 중 'Heap out of memory' 오류

bash

# docker-compose.yml environment 섹션에 추가
NODE_OPTIONS=--max-old-space-size=4096

Q8 해결

Node.js 힙 메모리 한도를 늘려줍니다. 기본값은 약 1.5 GB입니다. 근본 해결책은 Split In Batches로 데이터를 나누는 것입니다.

🟢 권한/계정 문제

Q9. 팀원이 워크플로우를 볼 수 없어요.

프로젝트 Settings → Members에서 해당 팀원이 추가되어 있는지 확인하세요. 프로젝트 단위로 접근 권한이 분리됩니다.

Q10. Owner 비밀번호를 잊었어요.

bash

docker compose exec n8n /bin/sh
n8n user-management:reset

Q10 해결

위 명령을 실행하면 모든 사용자 비밀번호가 초기화되고 재설정 링크가 발급됩니다. Owner 이메일 주소는 기억해야 합니다.

Q11. API Key가 작동하지 않아요.

Settings → API 메뉴에서 키가 활성화 상태인지 확인하세요. 헤더는 X-N8N-API-KEY 여야 하며, Authorization: Bearer 형식이 아닙니다.

Q12. 2FA를 설정했는데 코드가 맞지 않아요.

서버 시간이 맞지 않으면 TOTP 코드가 틀릴 수 있습니다. 서버에서 timedatectl status 로 시간을 확인하고, TZ=Asia/Seoul 환경변수가 설정되어 있는지 점검하세요.

🔵 MCP 문제

Q13. Claude Desktop에 n8n 연결이 안 돼요.

json

{
  "mcpServers": {
    "n8n": {
      "env": {
        "N8N_API_URL": "https://실제도메인/api/v1",
        "N8N_API_KEY": "실제_MCP_액세스_토큰"
      }
    }
  }
}

Q13 해결

Claude Desktop을 완전 종료 후 재시작하고, Settings → Instance-level MCP가 활성화 상태인지 확인하세요.

Q14. MCP Server Trigger로 만든 도구가 Claude에서 안 보여요.

워크플로우가 Published 상태인지 확인하세요. Draft 상태에서는 MCP 도구가 노출되지 않습니다.

Q15. MCP 도구 호출 시 'Tool not found' 오류

Tool Name에 공백이나 특수문자가 포함되어 있으면 인식에 실패합니다. 영문 소문자, 숫자, 하이픈(-), 언더스코어(_)만 사용하세요.

🟠 워크플로우/노드 오류

Q16. HTTP Request 노드에서 401 Unauthorized 오류

Credentials가 올바르게 연결되어 있는지 확인하세요. 토큰 방식이라면 Header Auth를 선택하고 Key는 Authorization, Value는 Bearer {토큰값} 형식으로 입력합니다.

Q17. 웹훅이 외부에서 호출되지 않아요.

WEBHOOK_URL 환경변수가 실제 도메인으로 설정되어 있는지 확인하세요. localhost로 설정되어 있으면 외부에서 접근할 수 없습니다. 워크플로우가 Active 상태여야 Production URL이 활성화됩니다.

Q18. Cron 트리거가 실행 안 돼요.

GENERIC_TIMEZONE=Asia/Seoul이 설정되어 있는지 확인하세요. 타임존이 맞지 않으면 예상 시간에 실행되지 않습니다. 워크플로우가 Active 상태인지도 확인하세요.

Q19. 노드 실행 중 'ENOMEM: not enough memory' 오류

bash

# 현재 메모리 사용량 확인
docker stats --no-stream

# 불필요한 컨테이너 정리
docker system prune -f

Q20. IF 노드에서 조건이 항상 false로 분기돼요.

데이터 타입을 확인하세요. 숫자처럼 보여도 문자열인 경우 === 비교에서 false가 됩니다. Expression에서 Number() 또는 toString()으로 타입을 맞춰주세요.

⚪ 데이터/크리덴셜 문제

Q21. 크리덴셜을 다른 서버로 이전했는데 '복호화 실패' 오류

N8N_ENCRYPTION_KEY가 기존 서버와 동일한지 확인하세요. 암호화 키가 다르면 기존 크리덴셜을 복호화할 수 없습니다. .env 파일의 키를 원본 값으로 복원한 뒤 컨테이너를 재시작하세요.

Q22. PostgreSQL 연결 오류 'FATAL: password authentication failed'

bash

# .env의 DB 비밀번호와 실제 postgres 비밀번호 일치 여부 확인
docker compose exec postgres psql -U n8n_user -d n8n_db

Q22 해결

비밀번호가 맞지 않으면 postgres 컨테이너를 내리고 볼륨을 삭제한 뒤 .env에 통일된 비밀번호로 다시 설정하세요. 주의: 볼륨 삭제 시 기존 데이터가 사라집니다. 백업 필수.

Q23. 워크플로우 내보내기(Export) 시 크리덴셜이 포함되나요?

아니오. n8n은 워크플로우 JSON 내보내기 시 크리덴셜 값을 포함하지 않습니다. 크리덴셜 ID만 포함되므로, 다른 환경에 가져온 뒤 크리덴셜을 새로 연결해야 합니다.

Q24. Google Sheets 노드에서 'Access denied' 오류

Google Cloud Console에서 서비스 계정에 해당 스프레드시트의 편집 권한을 부여했는지 확인하세요. 스프레드시트 공유 설정에서 서비스 계정 이메일(…@….iam.gserviceaccount.com)을 편집자로 추가해야 합니다.

🟣 업그레이드/마이그레이션

Q25. n8n 버전 업그레이드 방법

bash

# docker-compose.yml의 image 태그를 최신 버전으로 변경 후
docker compose pull n8n
docker compose up -d n8n

Q25 해결

업그레이드 전에 반드시 워크플로우와 크리덴셜을 백업하세요. major 버전 업그레이드(예: 0.x → 1.x)는 릴리스 노트의 Breaking Changes를 먼저 확인합니다.

Q26. 마이그레이션 후 워크플로우가 사라졌어요.

bash

# PostgreSQL 볼륨이 마운트되어 있는지 확인
docker volume ls | grep n8n

# 데이터 백업에서 복구
docker compose exec postgres pg_restore -U n8n_user -d n8n_db /backup/n8n_backup.dump

Q27. SQLite에서 PostgreSQL로 마이그레이션하는 방법

공식 n8n 문서의 데이터베이스 마이그레이션 가이드를 따르세요. n8n export:workflow --all --output=./backup 로 워크플로우를 JSON으로 내보내고, PostgreSQL 환경에서 n8n import:workflow --input=./backup 으로 가져옵니다. 크리덴셜은 수동으로 재연결이 필요합니다.

🔶 Queue Mode / 확장 문제

Q28. Queue Mode에서 워커가 작업을 가져가지 않아요.

EXECUTIONS_MODE=queue 설정이 main과 worker 컨테이너 모두에 적용되어 있는지 확인하세요. Redis 연결 정보(QUEUE_BULL_REDIS_HOST, QUEUE_BULL_REDIS_PORT)도 동일해야 합니다. docker compose logs n8n-worker-1 으로 워커 로그를 확인하세요.

Q29. Redis 연결 오류 'ECONNREFUSED'

bash

# Redis 컨테이너 상태 확인
docker compose ps redis

# Redis 직접 연결 테스트
docker compose exec redis redis-cli ping

Q29 해결

PING에 PONG이 돌아오지 않으면 Redis 컨테이너가 정상 실행 중이 아닙니다. docker compose restart redis 후 다시 시도하세요.

Q30. 커스텀 노드 업데이트 후 n8n에 반영이 안 돼요.

npm run build 로 재빌드한 뒤 n8n 컨테이너를 반드시 재시작해야 합니다. n8n은 시작 시 노드를 로드하므로, 빌드만 하고 재시작하지 않으면 변경사항이 반영되지 않습니다. docker compose restart n8n 을 실행하세요.

← 이전

부록 A — n8n 핵심 환경변수 레퍼런스

부록 C — MCP 클라이언트별 설정 치트시트

← 목차로 돌아가기