n8n으로 업무 자동화를 구축하다 보면 어제까지 멀쩡하던 워크플로우가 아침에 갑자기 멈추는 당혹스러운 상황이 발생합니다. 에러 로그를 열어보면 마주하게 되는 메시지는 대개 비슷합니다. SyntaxError: Unexpected token < 또는 Invalid JSON 같은 메시지들입니다.
이런 에러들은 대부분 외부 서비스와의, 통신 과정에서 발생하는 데이터 구조의 불일치 때문인데요. n8n 전문가의 관점에서 단순히 에러를 고치는 수준을 넘어 에러를 해결하는 노하우를 공유해 드립니다.
1. n8n의 핵심 메커니즘, 모든 것은 배열이다
JSON 에러를 해결하기 전 우리는 n8n이 데이터를 다루는 고유한 방식을 이해해야 합니다. n8n의 모든 데이터는 json 객체를 포함한 아이템의 배열 구조를 가집니다.
- 구조의 핵심: 우리가 다루는 텍스트나 숫자 데이터는 모두 json이라는 이름의 객체 안에 담겨 있습니다.
- 접근 방식: 익스프레션 에디터에서 $json.key라고 입력하는 것은 현재 아이템의 json 객체에서 특정 키의 값을 가져오라는 명령입니다.
실무에서 발생하는 파싱 에러의 대부분은 이 구조를 무시하고 데이터에 접근하려 할 때 발생합니다. 에러가 났다면 가장 먼저 Execution 탭에서 데이터의 타입이 문자열인지 객체인지 직접 확인하는 과정이 필요합니다.
2. 단골 에러 유형별 정밀 진단과 해결법
유형 1: Unexpected token < (HTML 응답 문제)
가장 흔하게 발생하는 에러입니다. JSON 데이터가 올 것으로 기대했지만 < 문자가 발견되었다는 것은 서버가 정상적인 데이터 대신 HTML 에러 페이지를 반환했다는 뜻입니다.
- 해결방법: HTTP Request 노드의 설정을 잠시 Response Format: String으로 변경하십시오. 그러면 깨진 JSON 대신 서버가 보낸 실제 에러 메시지를 눈으로 확인할 수 있습니다. 원인을 파악한 뒤 다시 설정을 되돌리는 것이 효율적입니다.
유형 2: AI 응답의 불완전한 JSON 형식
ChatGPT나 Gemini 같은 거대 언어 모델은 종종 JSON 외에 불필요한 설명을 덧붙이곤 합니다.
- 개선된 접근법: 프롬프트에 제약을 거는 것도 중요하지만 n8n의 AI Agent 노드 내에 있는 Output Parser 기능을 활용하여 구조화된 데이터를 강제하는 것이 가장 안정적입니다. 만약 구형 노드를 사용 중이라면 Code 노드에서 정규식을 활용하여 순수 JSON 영역만 추출하는 가공 단계를 추가해야 합니다.
유형 3: 빈 값 및 이중 파싱 문제
데이터가 null이거나 빈 문자열인 경우 또는 JSON 안에 또 다른 JSON이 문자열 형태로 들어 있는 경우입니다.
- 실무 팁: 익스프레션에서 단락 평가를 활용하여 값이 없을 경우를 대비한 기본값을 설정해 두십시오. 예를 들어 특정 필드 뒤에 || 기호와 함께 기본값을 적어두면 후속 노드가 데이터 부재로 인해 멈추는 것을 방지할 수 있습니다.
3. 에러를 막지 말고 관리하자
숙련된 설계자는 개별 노드마다 분기 처리를 하기보다 전역 에러 핸들링 시스템을 구축합니다.
- Error Workflow 설정: 워크플로우 설정 메뉴에서 별도의 에러 처리 워크플로우를 지정하고, 에러 발생 시 즉시 알림을 보내거나 재시도 로직을 실행하도록 중앙 집중 관리하는 것이 유지보수에 유리합니다.
- 데이터 다이어트: 불필요하게 거대한 데이터를 그대로 들고 다니면 메모리 초과 에러가 발생하기 쉬우므로, Edit Fields 노드를 활용하여 다음 단계에 꼭 필요한 데이터만 남기고 제거하는 습관이 필요합니다.
- 방어 코딩: Code 노드를 작성할 때는 반드시 try-catch 문을 사용하여 파싱 실패 시에도 워크플로우가 완전히 중단되지 않고 에러 로그를 반환하게 설계해야 합니다.
4. 안정적인 n8n 자동화를 시작해보세요
안정적인 n8n 자동화는 외부 서비스의 응답이 언제든 변할 수 있다고 가정하는 데서 시작합니다. 오늘 소개해 드린 응답 포맷 확인과 데이터 정제 그리고 전역 에러 핸들링 전략을 워크플로우에 적용해 보시기 바랍니다. 단순한 해결을 넘어 어떤 상황에서도 안정적으로 작동하는 견고한 시스템을 구축하실 수 있을겁니다.
추가로 궁금한 점이 있거나 특정 노드 설정에 도움이 필요하시면 언제든 의견을 남겨 주세요. 함께 고민하고 최선의 해결책을 찾아드리겠습니다.