업무 자동화의 강력한 도구인 n8n을 활용하다 보면 가장 자주 마주치며 우리를 당황하게 만드는 것이 바로 JSON 관련 에러입니다. 어제까지 정상적으로 작동하던 워크플로우가 갑자기 멈춰버리면 당혹스럽기 마련입니다. 특히 외부 API와의 통신이나 AI 노드를 활용한 자동화에서 발생하는 파싱 오류는 그 원인이 다양하여 초보자가 해결하기 쉽지 않습니다. 이번 글에서는 JSON 파싱 에러의 근본적인 원인을 분석하고 이를 완벽하게 해결하여 중단 없는 자동화 시스템을 구축하는 방법을 상세히 알아보겠습니다.
n8n 데이터 통신기초, 데이터는 배열 속에 있다
n8n의 에러를 해결하기 위한 첫 번째 단계는 이 도구가 데이터를 어떻게 취급하는지 이해하는 것입니다. n8n에서 흐르는 모든 데이터는 기본적으로 배열 형태를 띠고 있습니다. 하나의 노드가 실행되면 그 결과물은 여러 개의 아이템으로 구성된 리스트가 되며, 각 아이템은 JSON 객체를 포함하고 있습니다.
우리가 흔히 사용하는 데이터 접근 방식인 $json 표기법은 현재 처리 중인 특정 아이템의 JSON 내부 값을 가져오겠다는 선언입니다. 이 구조를 정확히 모르면 데이터가 분명히 눈에 보이는데도 왜 값을 불러오지 못하는지 이해할 수 없게 됩니다. 디버깅의 핵심은 항상 노드의 출력 결과가 배열인지 단일 객체인지 확인하는 것에서 시작해야 합니다.
대표적인 JSON 파싱 에러 유형
가장 흔하게 발생하는 에러 중 하나는 예상치 못한 토큰 오류입니다. 이는 보통 API 서버에서 JSON이 아닌 HTML 형식의 에러 페이지를 반환할 때 발생합니다. 서버 점검 중이거나 잘못된 경로로 요청을 보냈을 때 브라우저가 보는 것과 같은 HTML 코드가 n8n으로 들어오면, n8n은 이를 JSON으로 해석하려다 실패하게 됩니다.
이때는 당황하지 말고 HTTP Request 노드의 설정을 변경해야 합니다. 응답 형식을 문자열로 바꾼 뒤 출력되는 텍스트를 직접 확인하면 서버가 보내온 실제 에러 메시지를 읽을 수 있습니다. 이를 통해 인증 정보가 잘못되었는지 혹은 API 호출 제한에 걸렸는지를 명확히 파악할 수 있습니다.
AI 노드 활용 시 Invalid JSON 문제 해결
최근 ChatGPT나 Claude 같은 대규모 언어 모델을 워크플로우에 통합하는 사례가 늘고 있습니다. 하지만 AI는 항상 정제된 JSON만을 내놓지 않습니다. 답변 앞뒤에 붙는 인사말이나 설명 텍스트는 n8n의 후속 노드가 데이터를 인식하는 데 방해가 됩니다.
이를 방지하기 위해서는 프롬프트 엔지니어링 단계에서 명확한 제약을 주어야 합니다. 오직 JSON 구조만 출력하도록 지시하고, 불필요한 서술을 금지해야 합니다. 그럼에도 불구하고 발생할 수 있는 오류를 막기 위해 Code 노드를 중간에 배치하는 것이 좋습니다. 정규 표현식을 사용하여 텍스트 중에서 중괄호로 시작하고 끝나는 부분만 골라내어 다시 파싱하는 로직을 구현하면 자동화의 안정성이 높아집니다.
복잡한 중첩 데이터 구조
API 응답 데이터는 종종 여러 층위로 겹쳐진 중첩 구조를 가집니다. 예를 들어 사용자 정보 내에 주소 목록이 있고, 그 목록의 첫 번째 항목에서 도시 이름을 가져와야 하는 상황입니다. 이때는 점 표기법과 배열 인덱스를 조합하여 경로를 지정해야 합니다.
데이터가 복잡해질수록 n8n의 표기법을 정확히 사용하는 것이 중요합니다. 만약 데이터 구조가 너무 깊어 접근이 어렵다면, 중간에 Item Lists 노드를 활용하여 배열을 개별 아이템으로 쪼개거나 Set 노드를 통해 필요한 값만 상위 레벨로 끌어올리는 전처리 과정을 거치는 것이 좋습니다. 이는 나중에 워크플로우를 유지보수할 때도 가독성을 높여주는 효과가 있습니다.
안정적인 자동화를 위한 설계
에러는 발생한 뒤에 고치는 것보다 발생할 상황을 미리 대비하는 것이 상책입니다. n8n 워크플로우 설계 시 몇 가지 원칙을 지키면 운영 효율이 달라집니다.
첫째로 모든 외부 통신 노드에는 에러 발생 시에도 워크플로우가 멈추지 않도록 설정을 검토해야 합니다. 무조건 멈추게 하기보다는 에러 상황을 데이터의 한 종류로 받아들이고, 이를 별도의 경로로 흘려보내 관리자에게 알림을 주도록 설계해야 합니다.
둘째로 데이터 타입의 엄격한 관리가 필요합니다. 숫자로 들어와야 할 값이 문자열로 들어오거나, 데이터가 비어있는 상태로 전달될 때를 대비해 기본값을 설정해두는 습관이 필요합니다. 자바스크립트의 논리 연산자를 활용하면 값이 없을 때 대체 텍스트를 넣는 등의 처리를 간단하게 수행할 수 있습니다.
데이터 제어 능력이 자동화의 수준을 결정
결국 n8n을 잘 다룬다는 것은 데이터를 얼마나 자유자재로 가공하고 예외 상황을 통제할 수 있느냐에 달려 있습니다. JSON 파싱 에러는 우리를 괴롭히는 장애물이 아니라, 워크플로우의 취약점을 알려주는 이정표와 같습니다. 이번 가이드에서 다룬 유형별 해결책과 설계 원칙을 적용한다면, 어떤 복잡한 외부 서비스와 연동하더라도 흔들림 없는 자동화 시스템을 완성할 수 있을 것입니다.
데이터의 흐름을 정확히 꿰뚫어 보고 에러에 유연하게 대처하는 능력을 갖추어, 업무 효율을 높여보시기 바랍니다. 자동화 과정에서 겪는 지속적인 테스트와 데이터 구조에서 해결방법을 찾아낼 수 있습니다.