대부분의 n8n docker 설치 오류는 코드가 아닌, 시스템의 기본 전제를 오해하는 데서 시작됩니다. 터미널에 출력되는 붉은 경고 메시지는 현상이자 결과일 뿐, 문제의 진짜 원인은 보이지 않는 설정 파일과 네트워크 계층 깊숙이 숨어있습니다. 이 오류들은 n8n이나 Docker의 결함이 아니라, 우리가 분산 시스템의 작동 방식을 어떻게 해석하고 있는지를 비추는 거울입니다.
설정(Configuration) 오류: 보이지 않는 함정들
시스템 설정의 미세한 균열은 전체 구조의 붕괴로 이어집니다. 대부분의 n8n 로컬 설치 실패는 이 단계에서 발생하며, 이는 단순한 오타가 아니라 시스템 컴포넌트 간의 약속을 위반한 결과입니다. 각 설정 값은 독립적인 존재가 아니라, 전체 시스템의 논리적 흐름을 구성하는 하나의 노드입니다.
Q1: docker-compose up 실행 시 “.env file not found” 오류가 발생합니다.
A: 이 오류는 docker-compose가 환경 변수를 정의하는 .env 파일을 찾지 못했다는 명백한 신호입니다. 하지만 진짜 문제는 파일의 부재가 아니라, 실행 위치의 문제입니다. docker-compose.yml 파일이 위치한 디렉토리에서 명령을 실행했는지 확인해야 합니다. Docker 공식 문서에서 설명하듯, .env 파일은 명령이 실행되는 ‘현재 작업 디렉토리’를 기준으로 탐색됩니다. 따라서 터미널의 현재 경로가 프로젝트 루트가 아니라면 Docker는 당연히 설정 파일을 읽을 수 없습니다. (.env 파일의 위치와 현재 작업 디렉토리 규칙)
Q2: .env 파일에 데이터베이스 정보를 올바르게 입력했는데도 연결에 실패합니다.
A: docker-compose.yml 내부에서 정의된 서비스 이름을 호스트 주소로 사용하고 있는지 확인해야 합니다. 예를 들어, PostgreSQL 서비스 이름이 postgres라면, .env 파일의 DB_HOST 값은 localhost나 127.0.0.1이 아닌 postgres여야 합니다. Docker Compose는 자체적인 가상 네트워크를 생성하며, 공식 문서에서 설명하는 Docker Compose 내부 DNS와 서비스명 접근 규칙에 따라, 동일 네트워크 내 컨테이너들은 서비스 이름을 호스트명처럼 사용하여 서로 통신할 수 있습니다. 이는 현실의 주소 체계가 아닌, 격리된 내부 생태계의 규칙을 따라야 함을 의미합니다.
Q3: n8n docker-compose 설정에서 웹훅(Webhook) URL이 localhost로 잡힙니다.
A: WEBHOOKURL 환경 변수를 명시적으로 설정해야 합니다. n8n은 외부 서비스와 통신해야 하므로, 컨테이너 내부의 localhost 주소는 외부에서 접근할 수 없습니다. Public IP 주소나 도메인 이름을 .env 파일의 WEBHOOKURL에 https://your.domain.com/ 형식으로 정확히 지정해야 합니다. 이는 내부 시스템의 언어(localhost)를 외부 세계의 언어(Public Domain)로 번역하는 과정과 같습니다.
Q4: 타임존(Timezone)이 맞지 않아 워크플로우 실행 시간이 다르게 기록됩니다.
A: GENERICTIMEZONE 환경 변수를 설정해야 합니다. 컨테이너는 기본적으로 UTC 시간대를 사용합니다. .env 파일에 GENERICTIMEZONE=Asia/Seoul과 같이 거주 지역의 타임존을 명시적으로 선언해야 합니다. 시간은 절대적인 개념이 아니라, 시스템이 동의한 상대적인 약속이라는 점을 기억해야 합니다.
Q5: SSL/TLS 설정 후 Error: self-signed certificate 오류가 발생합니다.
A: Node.js가 자체 서명된 인증서를 신뢰하지 않기 때문에 발생하는 문제입니다. 개발 환경이라면 NODETLSREJECTUNAUTHORIZED=0 환경 변수를 추가하여 임시로 해결할 수 있습니다. 하지만 Node.js 공식 문서에서 경고하듯, 이 옵션은 TLS 인증서의 유효성 검사를 완전히 비활성화하므로 프로덕션 환경에서는 절대 사용해서는 안 됩니다. 잠재적인 중간자 공격에 취약해질 수 있으므로, 프로덕션에서는 반드시 Let’s Encrypt와 같은 신뢰할 수 있는 기관(CA)에서 발급한 인증서를 사용해야 합니다. (NODETLSREJECTUNAUTHORIZED 보안 영향)
네트워크(Network) 오류: 연결의 미로
네트워크 오류는 시스템의 혈관이 막힌 것과 같습니다. 데이터가 흘러야 할 길이 막히거나 잘못된 경로로 향할 때, 시스템은 기능 부전에 빠집니다. docker n8n 설치 과정에서 겪는 대부분의 네트워크 문제는 포트 충돌이나 방화벽 규칙이라는 단순한 원인에서 비롯됩니다.
Q6: Port is already allocated 또는 address already in use 오류가 발생하며 컨테이너가 시작되지 않습니다.
A: n8n이 사용하려는 5678 포트를 다른 애플리케이션이 이미 점유하고 있다는 의미입니다. 이는 시스템 자원의 독점적 소유권 문제와 같습니다. docker-compose.yml 파일에서 포트 매핑을 “5678:5678” 에서 “8080:5678” 과 같이 변경하여 호스트의 다른 포트(예: 8080)를 n8n 컨테이너의 5678 포트로 연결해야 합니다.
Q7: n8n 컨테이너 내부에서 외부 API로 요청을 보낼 수 없습니다.
A: 컨테이너의 DNS 설정 문제일 가능성이 높습니다. Docker는 기본적으로 호스트의 DNS 설정을 상속받지만, 때로는 제대로 작동하지 않을 수 있습니다. docker-compose.yml 파일의 n8n 서비스에 dns: [8.8.8.8, 8.8.4.4] 와 같이 Google DNS 서버를 명시적으로 지정하여 해결할 수 있습니다.
Q8: 외부에서 n8n UI에 접속할 수 없습니다.
A: 가장 먼저 확인할 것은 방화벽(Firewall) 설정입니다. 클라우드 서버(AWS, GCP 등)를 사용 중이라면 보안 그룹에서 n8n이 사용하는 포트(기본 5678)에 대한 인바운드 규칙을 허용해야 합니다. 서버 자체의 방화벽(UFW, firewalld) 설정도 확인해야 합니다. 문은 열려 있지만, 경비원(방화벽)이 출입을 막고 있는 상황입니다.
Q9: 여러 Docker 프로젝트를 동시에 실행할 때 네트워크 충돌이 발생합니다.
A: 기본적으로 Docker Compose는 프로젝트 폴더 이름을 기반으로 projectnamedefault 형태의 네트워크를 생성합니다. 만약 다른 프로젝트에서 동일한 네트워크 이름을 사용하거나 서브넷이 겹치면 충돌이 발생할 수 있습니다. docker-compose.yml 파일 최상단에 name: myuniqueprojectname을 추가하여 프로젝트 이름을 명시적으로 지정하면 충돌을 피할 수 있습니다.
Q10: 리버스 프록시(Nginx, Traefik 등) 뒤에서 n8n을 실행할 때 CSS나 스크립트가 깨집니다.
A: 리버스 프록시가 Host 헤더나 프로토콜(HTTP/HTTPS) 정보를 제대로 전달하지 못하기 때문입니다. Nginx의 경우, proxysetheader Host $host;, proxysetheader X-Forwarded-Proto $scheme; 와 같은 설정을 추가해야 합니다. n8n이 자신이 어떤 도메인과 프로토콜로 서비스되고 있는지 정확히 인지하도록 외부 세계의 정보를 내부로 전달해주는 과정입니다.
데이터베이스(Database) & 볼륨(Volume) 오류: 데이터 영속성의 붕괴
데이터는 시스템의 기억입니다. 볼륨과 데이터베이스 오류는 시스템이 기억상실증에 걸리는 것과 같습니다. n8n 도커 설치 시 데이터 영속성을 확보하지 못하면, 컨테이너를 재시작할 때마다 모든 워크플로우와 자격 증명이 사라지는 재앙을 맞게 됩니다.
Q11: 컨테이너를 재시작하면 모든 데이터(워크플로우, 인증 정보)가 사라집니다.
A: Docker 볼륨(Volume) 마운트 설정이 누락되었기 때문입니다. 컨테이너의 파일 시스템은 휘발성입니다. 데이터를 영구적으로 저장하려면 호스트 머신의 특정 디렉토리를 컨테이너 내부의 /root/.n8n 디렉토리에 마운트해야 합니다. docker-compose.yml 파일에 volumes: – n8n_data:/root/.n8n 와 같은 설정을 추가하여 컨테이너의 기억을 호스트의 물리적 공간에 각인시켜야 합니다.
Q12: permission denied 오류와 함께 볼륨 마운트에 실패합니다.
A: 호스트 머신에 마운트하려는 디렉토리의 소유권 및 권한 문제입니다. n8n 컨테이너는 기본적으로 node 사용자(UID 1000)로 실행됩니다. 호스트의 마운트 대상 디렉토리 소유자를 동일한 UID로 변경(sudo chown -R 1000:1000 /path/to/n8n/data)하면 해결됩니다. 이는 시스템의 다른 두 사용자(호스트, 컨테이너) 간의 소유권 계약을 체결하는 것과 같습니다.
Q13: PostgreSQL 연결 시 FATAL: password authentication failed for user “user” 오류가 발생합니다.
A: .env 파일에 정의된 데이터베이스 사용자 이름, 비밀번호, 데이터베이스 이름이 PostgreSQL 컨테이너를 초기화할 때 사용된 환경 변수(POSTGRESUSER, POSTGRESPASSWORD, POSTGRES_DB)와 정확히 일치하는지 교차 확인해야 합니다. 단 하나의 문자라도 다르면, 시스템은 당신을 침입자로 간주할 것입니다.
Q14: SQLite를 사용 중인데 데이터베이스 파일이 잠겼다는 오류(SQLITE_BUSY)가 발생합니다.
A: SQLite는 동시 쓰기 작업에 취약합니다. 여러 워크플로우가 동시에 데이터베이스에 쓰려고 할 때 이 문제가 발생할 수 있습니다. 사용량이 많은 환경이라면 PostgreSQL이나 MySQL과 같은 강력한 동시성 제어 기능을 갖춘 데이터베이스로 전환하는 것이 근본적인 해결책입니다. 이는 1차선 도로를 8차선 고속도로로 확장하는 것과 같습니다.
Q15: 볼륨을 사용하는데도 데이터베이스 마이그레이션이 반복적으로 실행됩니다.
A: n8n의 버전 업데이트 후 발생할 수 있는 문제입니다. 컨테이너를 중지하고, 볼륨을 백업한 뒤, docker-compose down -v 명령으로 볼륨까지 완전히 삭제한 후 다시 시작하면 해결될 수 있습니다. 하지만 이 경우 모든 데이터가 삭제되므로, 반드시 백업을 먼저 수행해야 합니다. 이는 낡은 건물을 허물고 새 건물을 짓기 전, 중요한 자산을 미리 옮기는 것과 같습니다.
실행(Runtime) 및 자원(Resource) 오류: 시스템의 비명
Q16: n8n 컨테이너가 이유 없이 계속 재시작됩니다.
A: 대부분 메모리 부족(Out of Memory) 문제입니다. docker stats 명령으로 해당 컨테이너의 메모리 사용량을 확인해보세요. 복잡한 워크플로우나 대용량 데이터를 처리할 때 메모리 사용량이 급증할 수 있습니다. Docker 실행 옵션이나 docker-compose.yml에서 컨테이너에 할당된 메모리를 늘려주어야 합니다.
Q17: 워크플로우 실행 중 Exited with code 137 오류가 발생합니다.
A: 코드 137은 리눅스 시스템이 메모리 부족으로 프로세스를 강제 종료(SIGKILL)했음을 의미하는 명백한 신호입니다. 이는 단순히 일시적인 오류 해결을 넘어, 자동화 시스템의 근본적인 아키텍처를 재고해야 한다는 경고입니다. 개별 오류를 해결하는 단계를 넘어, 안정적이고 확장 가능한 자동화 엔진을 구축하려면 시스템 설계에 대한 심도 깊은 접근이 필요합니다. 월 $6로 Zapier를 대체하는 n8n 셀프 호스팅 완벽 구축 가이드는 이러한 근본적인 문제 해결과 장기적인 운영 전략을 위한 청사진을 제공합니다.
Q18: npm ERR! … 로 시작하는 긴 오류 로그와 함께 빌드에 실패합니다.
A: 커스텀 이미지를 빌드하는 경우, Dockerfile 내부의 npm install 과정에서 의존성 패키지 설치에 실패한 것입니다. 네트워크 문제, 패키지 버전 충돌, 또는 npm 레지스트리 문제일 수 있습니다. Docker 빌드 캐시를 삭제(docker builder prune)하고 다시 시도하거나, package-lock.json 파일을 삭제하여 의존성을 새로고침하는 방법이 있습니다.
Q19: 워크플로우를 실행하면 UI가 멈추거나 반응이 없습니다.
A: 프론트엔드와 백엔드 간의 통신 문제일 수도 있지만, 대부분은 백엔드에서 매우 무거운 작업을 처리하느라 다른 요청에 응답하지 못하는 경우입니다. 특히 바이너리 파일 처리나 대규모 데이터 루프는 n8n의 메인 스레드를 차단할 수 있습니다. 이런 작업은 별도의 워크플로우로 분리하거나, Queue 모드를 활성화하여 비동기적으로 처리하는 것을 고려해야 합니다.
Q20: 로그에 특별한 오류 메시지 없이 컨테이너가 그냥 종료됩니다.
A: docker logs
결국 모든 오류 로그는 시스템이 우리에게 보내는 솔직한 대화의 시작입니다. 그 코드를 해독하는 것은 기술을 넘어, 보이지 않는 구조와 관계를 파악하는 인식의 문제이며, 이것이 바로 AI 시대에 대체 불가능한 인간의 영역입니다.